HP 9000 Series 200/300 Computers 



EelS 



EWLETT 
PACKARD 



Pascal 3.1 Workstation System 

Vol. I: Main Command Level and Subsystems 




Pascal 3.1 Workstation System 

Vol. I: Main Command Level and Subsystems 

for the HP 9000 Series 200/300 Computers 



Manual Reorder No. 98615-90022 




) Copyright 1985, Hewlett-Packard Company. 

This document contains proprietary information which is protected by copyright. All rights are reserved. No part of this 
document may be photocopied, reproduced or translated to another language without the prior written consent of 
Hewlett-Packard Company. The information contained in this document is subject to change without notice. 

Use of this manual and flexible disc(s) or tape cartridge(s) supplied for this pack is restricted to this product only. 
Additional copies of the programs can be made for security and back-up purposes only. Resale of the programs 
in their present form or with alterations, is expressly prohibited. 

Restricted Rights Legend 
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in paragraph (b)(3)(B) of the 
Rights in Technical Data and Software clause in DAR 7-104.9(a). 



Hewlett-Packard Company 

3404 East Harmony Road. Fort Collins. Colorado 80525 



Printing History 



New editions of this manual will incorporate all material updated since the previous edition. Update 
packages may be issued between editions and contain replacement and additional pages to be 
merged into the manual by the user. Each updated page will be indicated by a revision date at the 
bottom of the page. A vertical bar in the margin indicates the changes on each page. Note that pages 
which are rearranged due to changes on a previous page are not considered revised. 

The manual printing date and part number indicate its current edition. The printing date changes 
when a new edition is printed. (Minor corrections and updates which are incorporated at reprint do 
not cause the date to change. ) The manual part number changes when extensive technical changes 
are incorporated. 

May 1985... Edition 1 



NOTICE 

The information contained in this document is subject to change without notice. 

HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MANUAL, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett- 
Packard shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in 
connection with the furnishing, performance, or use of this material. 

WARRANTY 

A copy of the specific warranty terms applicable to your Hewlett-Packard product and replacement parts can be obtained from 
your local Sales and Service Office. 



Ill 



Table of Contents 



Chapter 1: Manual Overview 1 

Introduction 1 

Before Reading this Manual 1 

Preview of Chapters in Volume 1 2 

Preview of Chapters in Volume II 3 

Chapter 2: The Main Command Level 5 

Introduction 5 

Main Command Prompt 5 

Main Command Quick Reference 6 

Main Command Reference 7 

eXecute 8 

Initialize 9 

Memory volume 10 

New sysvol 12 

Permanent 13 

Run 14 

Stream 15 

User restart 18 

Version 19 

What 21 

Chapter 3: File System 23 

Introduction 23 

Primary Vs. Secondary Storage 23 

Pascal Volumes 24 

Volumes 24 

Logical Units 25 

The System Volume and Default Volume 26 

Files 27 

File Naming Conventions 28 

File Specifications and File Names 28 

Syntax of File Names 31 

File Types Derived from File Names 31 

File names (LIF) 32 

File Names (Workstation 1.0 Directory) 33 

File Names (SRM System) 33 

File Size Specification 33 

Several Directory Organizations Allowed 34 

File Name Suffixes and File Types 34 

Suppressing the Suffix 35 

Translating Files from One Data Type to Another 36 



IV 



Wildcards 37 

File Names to Avoid 39 

Allowable File Names 39 

File Name Length 40 

No Room on Volume 40 

The Shared Resource Management System 41 

Hierarchical directories 41 

Notation 42 

SRM Units and Volumes 42 

Moving Up and Down the Hierarchy 43 

Default Volume Vs Current Working Directory 45 

SRM Concurrent File Access 46 

SRM Access Rights 46 

Chapter 4: The Editor 47 

Introduction 47 

Entering the Editor 48 

Creating a Text File 49 

The Editor Prompt 49 

A Sample Editor Session 50 

Creating Text 50 

Storing your File and Returning to the Editor 51 

Copying Text from Other Files 52 

Confirming or Aborting Commands 53 

Moving the Cursor 54 

Deleting Text 55 

Recovering Deleted Text 56 

Moving and Duplicating Text 56 

Changing and Altering Text 57 

Formatting Text 62 

Exiting the Editor and Saving the File 66 

Making a Backup Copy 67 

A Closer Look 68 

The Cursor 68 

The Anchor 68 

The Screen as a Window into a File 68 

Memory and File Sizes 69 

Structure of Text Files 70 

Using Workfiles in the Editor 70 

Stream Files and the ANYCHAR Key 71 

I/O Errors (Entering and Exiting the Editor) 71 

Editor Commands 72 

Editor Command Summary 72 

Command Syntax and Semantics 73 

Adjust 74 

Copy 76 

Delete 78 

Equals ( = ) 80 



Find 81 

Insert 84 

Jump 87 

Margin 88 

Page 89 

Quit 90 

Replace 92 

Set 95 

Verify 99 

exchange 100 

Zap 102 

Chapter 5:: The Filer 103 

Introduction 103 

Entering the Filer 104 

The Filer Prompt 104 

Filer Operations 105 

A Sample Filer Session 105 

Finding Out What Devices are Accessible 105 

The Default and System Volumes 106 

Changing the Default Volume 106 

The System Volume 107 

Listing a Directory 108 

Getting a More Detailed Listing 109 

A Few Words About Wildcards Ill 

Translating Text Files Ill 

Sending File Listings to the Printer and Screen 112 

Copying Entire Volumes: Backup Copies 113 

Creating a Directory 115 

Copying Files from Volume to Volume 116 

Renaming Files and Volumes 119 

Removing Files 120 

Leaving the Filer 121 

The System Workfile (A Convenient Scratchpad) 121 

Filer Commands 122 

Filer Command Summary 122 

Command Syntax and Semantics 123 

Access 126 

Bad sector 128 

Change 129 

Duplicate-link 131 

Extended directory 132 

Filecopy 135 

Get 139 

Krunch 140 

List directory 142 

Make 144 

New 146 



VI 



Prefix 147 

Quit 149 

Remove 150 

Save 152 

Translate 153 

Unit directory 155 

Volumes 157 

What 158 

Zero 159 

Chapter 6: Pascal Compiler 161 

Introduction 161 

Steps In Program Development 162 

Prepare the Source Program 162 

Invoke the Compiler 162 

Handling Syntax Errors 163 

Interpreting the Compilation Listing 164 

Running the Compiled Program 165 

Using a Workfile 165 

Debugging 166 

Modules 167 

Module Structure 167 

Developing and Testing a Module 170 

An Illustration 172 

Compiling a Module Separately 172 

How the Compiler Finds Library Modules 173 

How the Loader Finds Library Modules 175 

A Subtle Point 176 

SINCLUDE Files 176 

Miscellaneous 176 

What Can Go Wrong? 177 

Can't Run the Compiler 177 

Errors 900 thru 908 177 

Errors When Importing Library Modules 178 

Not Enough Memory 178 

Insufficient Space for Global Variables 178 

Errors 403 thru 409 178 

Compiler Options 179 

ALIAS 180 

ALLOW-PACKED 181 

ANSI 182 

CALLABS 183 

CODE 184 

CODE_OFFSETS 185 

COPYRIGHT 186 

DEBUG 187 

DEF 188 

FLOAT_HDW 189 



Vll 



HEAP_DISPOSE 190 

IF 191 

INCLUDE 192 

IOCHECK 193 

LINENUM 194 

LINES 195 

LIST 196 

OVFLCHECK 197 

PAGE 198 

PAGEWIDTH 199 

PARTIAL_EVAL 200 

RANGE 201 

REF 202 

SAVE_CONST 203 

SEARCH 204 

SEARCH_SIZE 205 

STACKCHECK 206 

SWITCH_STRPOS 207 

SYSPROG 208 

TABLES 209 

UCSD 210 

WARN 211 

How Pascal Programs Use the Stack 212 

The Pascal Stack 212 

Global Variables 212 

Procedure Calls 213 

Function Calls 214 

Parameter Passing Mechanisms 214 

Function Results 215 

Chapter 7: The Assembler 221 

Introduction 221 

Operating the Assembler 222 

Invoking the Assembler 222 

Source File Specification 222 

Listing File Information 222 

Object File Specification 223 

Interpreting the Listing 224 

The Programming System 225 

The IMPORT Text 226 

The DEF Table 226 

The EXT Table 227 

Declaring the Module Name 228 

Passing Parameters 228 

Declaring Global Variables 229 

Referencing Global Variables 229 

Referencing Other Module's Globals 230 

Local Variables 230 



VIM 



Module Initialization 233 

Error Recovery 233 

Exception Coding 235 

Returning to Pascal 235 

Declaring External Procedures 236 

Instruction Syntax 237 

General Syntax 237 

Line Labels 238 

Opcodes 239 

Operands 241 

Addressing Modes 245 

Comments and Comment Lines 247 

MC68881 Floating Point Co-processor Support 249 

Assembler Support of the Co-processor 249 

Assembler Pseudo-Op Reference 250 

COM 250 

DC 251 

DECIMAL 251 

DEF 252 

DS 252 

END 253 

EQU 253 

INCLUDE 253 

LLEN 254 

LIST 254 

LMODE 255 

LPRINT 255 

MNAME 256 

NOLIST 256 

NOOBJ 257 

NOSYMS 257 

ORG 258 

PAGE 258 

REFA 259 

REFR 259 

RMODE 260 

RORG 260 

SMODE 261 

SPC 261 

SPRINT 261 

SRC 262 

START 262 

TTL 262 

The Examples 263 

The Sample Pascal Programs 263 

The Sample Pascal Module 264 

The Disassembly of the Module 265 

The Assembly Language Module 267 



IX 



Chapter 8: The Librarian 271 

Introduction 271 

Prerequisites 271 

Library Overview 272 

Modules and Libraries 272 

What the Librarian Does 272 

Example Modules 273 

Compiling and Running the Example Program 275 

Entering the Librarian 278 

Setting Up Mass Storage 279 

Creating Libraries of Object Modules 280 

Adding Modules to the System Library 280 

Making Your Own Library 282 

Linking Object Files Together 283 

Getting Detailed Object File Information 286 

The Text and Table Commands 287 

The Unassemble Commands 288 

Creating a New Boot File 292 

Librarian Command Reference 293 

Glossary of Object Code Terminology 296 

DEF Table (Definition Symbol Table) 296 

DEFINE SOURCE 296 

EXT Table (External Symbol Table) 297 

EXPORT 298 

Flags 298 

General Value or Address Record (GVR) 299 

IMPLEMENT 299 

IMPORT 299 

LIBRARIAN 299 

Library 300 

LIBRARY 300 

Object File 300 

Object Module 300 

Pascal Module 300 

REF Tables 301 

Reference Pointer 301 

System Library 302 

Text Record 302 

Chapter 9: The Debugger 303 

Introduction 303 

Is the Debugger Loaded? 303 

A Sample Session 304 

The Example Program 304 

Please Participate 305 

Loading the Debugger 305 

A Note about Key Notations 306 

Is the Debugger Installed? 307 



Invoking the Debugger 307 

The Debugger Command Screen 308 

Single-Stepping a Program 309 

Slow Program Execution 309 

Returning to the Debugger Command Screen 309 

Toggling Between Screens 309 

Screen Dumps 310 

A Look at the Queue 310 

Displaying Data 310 

Controlling Execution with Breakpoints 313 

The Pause Function and Breakpoints 316 

Executing a Number of Statements 316 

Tracing Program Flow through Procedures 317 

A Look at the Stack Frame 318 

Examining Variables 318 

Examining Consecutive Memory Locations 320 

Formats for Structured Variables 321 

Changing Memory Contents 322 

Static and Dynamic Links 323 

Exception Trapping 324 

Generating Escapes 325 

A Note about Assembly Language Programs 325 

Debugger Keyboard 327 

A Note about Key Notations 327 

Is the Debugger Installed? 327 

Calling the Debugger from the Main Command Level 328 

Step Modes 328 

Command Mode 328 

Debugger Command Summary 331 

Breakpoint Commands 331 

Call Command 331 

Display Commands 331 

Dump Commands 331 

Escape Code Commands 331 

Format Commands 331 

Go Commands 331 

IF, ELSE, and END Commands 332 

Open Memory Commands 332 

Procedure Commands 332 

Queue Commands 332 

Register Operations 332 

Softkey Commands 332 

System Boot Command 332 

Trace Commands 332 

Walk Procedure Links Commands 332 

Debugger Command Reference 333 

Debugger Expressions 333 

Multiple Commands on a Line 334 



XI 



Breakpoint Commands 335 

B 335 

BA 335 

BC 336 

BD 336 

BS 337 

The Call Command 338 

Display Command 339 

D 339 

Dump Commands 341 

DA 341 

DG 341 

Escape Code Commands 342 

EC 342 

ET 342 

ETC 343 

ETN 343 

Format Commands 344 

FB 344 

FH 344 

FI 344 

FO 344 

FU 344 

Go Commands 345 

G 345 

GF 345 

GT 346 

GTF 346 

IF, ELSE, and END Commands 347 

Open Memory Commands 349 

OL, OW, OB 349 

Semantics 349 

Procedure Commands 350 

PN 350 

PX 350 

Queue Commands 351 

Q 351 

QE 351 

QS 351 

Softkey Commands 352 

"K0" thru "K9" 352 

Register Operations 353 

System Boot 353 

Trace Commands 354 

T 354 

TD 354 

TQ 354 

TT 355 



Xll 



Walking the Procedure Links 356 

WD 356 

WR 356 

WS 356 

Technical Reference 357 

System History 358 

Pascal 1.0 358 

Pascal 2.0 and 2.1 359 

Pascal 3.0 362 

Pascal 3.01 366 

Pascal 3.1 367 

File Interchange Between Pascal and BASIC 371 

Module Names Used by the Operating System 373 

Physical Memory Map 375 

Full 16 Megabyte Addressing Range 375 

A Hypothetical RAM Configuration 376 

The Overall Memory Map 377 

Memory Mapped I/O 378 

External I/O 378 

Internal I/O 379 

The Software Memory Map 381 

Character Sets 383 

U.S. ASCII Character Set 384 

U.S. ASCII Character Set 385 

U.S. /European Display Characters 386 

U.S. /European Display Characters 387 

U.S. /European Display Characters 388 

U.S. /European Display Characters 390 

U.S./Eurpoean Display Characters 391 

Katakana Display Characters 392 

Katakana Display Characters 393 

Monochrome Highlight Characters 394 

Color Highlight Characters 394 

Command Summaries 395 

Main Command Level Summary 395 

Editor Command Summary 396 

Filer Command Summary 397 

Librarian Command Summary 398 

Debugger Command Summary 399 

Glossary 401 



Xlll 



Error Messages 407 

Unreported Errors 407 

Boot-Time Errors 408 

Run-Time Errors 408 

I/O System Errors 409 

I/O Library Errors 410 

Graphics Errors 411 

Loader/SEGMENTER Errors 412 

SEGMENTER Errors 412 

Loader Boot-Time Errors 412 

Pascal Compiler Errors 413 

ANSI/ISO Pascal Errors 413 

Compiler Options 414 

Implementation Restrictions 415 

Non-ISO Language Features 415 

Assembler Errors 417 

Error Messages 417 

Debugger Error Messages/Conditions 419 

Subject Index 421 



XIV 



Manual Overview 



Chapter 



Introduction 

This is Volume I of a two-volume manual that describes using the Pascal 3. 1 Workstation System. It 
shows how to use the Main Command Level and the subsystems of the Pascal Workstation 
"environment" — the Editor, Filer, Compiler, Assembler, Librarian, and Debugger - and how they 
interact to provide you with a powerful Pascal program development tool. 

Volume II focuses on programming and configuration of the system. 

Before Reading this Manual 

Here are the manuals that you should have read before reading this manual. 

Documentation Guide 

This guide describes each manual in the documentation set. It will help you to learn where the 
various parts of the system are described. 

Computer Installation Guides 

You should have already set up your computer hardware according to the instructions in the 
Installation Guide for your particular computer. 

Peripheral Installation Guide 

If you have peripheral devices, such as disc drives and printers, you should have set them up 
according to the instructions given in this manual. It contains pertinent information taken from each 
supported peripheral's installation/operating manual. 

Pascal User's Guide 

You should have booted the Pascal system according to the instructions in the Pascal User's Guide. 
This manual also describes the software configuration required for various peripheral devices. 

You may have also followed along with the examples to learn how to begin using the system to 
enter and compile a few simple Pascal programs, although that is not mandatory due to similar 
coverage in this manual. 

The Pascal Textbook 

If you are not familiar with the Pascal language, you may want to first read or scan An Introduction 
to Programming and Problem Solving with Pascal (included in the manual set sent with your 
system). 
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Volume II: Programming and Configuration Topics 

The second volume of this manual is similar to the Pascal textbook described in the last paragraph, 
but it presents programming techniques that are specific to the Workstation Pascal programming 
language; i.e., the extensions to "standard" Pascal that are provided by the Workstation. As with 
the Pascal textbook mentioned above, you may want to read or scan Volume II of this manual 
before delving too deeply into this volume. 

Previous Workstation Pascal Manuals 

If you are familiar with the documentation for earlier versions of the Pascal Workstation System, 
you may be happy to know that this manual is a later edition of the Pascal User's Manual. However, 
this manual describes only Version 3. 1 of the Pascal Workstation system. 



Note 

The main text of this manual does not generally discuss earlier versions 
of the system; however, the "System History" section of the "Technical 
Reference" appendix of this manual will help you if you are upgrading 
from an earlier version of the Workstation Pascal System. 

Other Manuals 

This manual does not generally assume that you are familiar with any of the other languages and 
systems available for this series of HP computers, although references are occasionally made to 
some of these other languages where appropriate (such as BASIC). 

Previews of Chapters in Volume I 

Here are brief previews of the contents of each of the remaining chapters of this manual. 

Chapter 2: The Main Command Level 

This chapter describes the commands available in the "Main Level" of the Workstation System. 

Chapter 3: The File System 

This chapter introduces you to the Workstation File System. It describes how the logical units and 
volumes are organized. However, it does not describe access of files from Pascal programs, which is 
covered in the subsequent "Programming with Files" chapter. 

Chapter 4: The Editor 

A program usually starts out as an idea. The Editor's function is to provide a useful environment for 
the translation of thoughts into actual programs or documents. This chapter fully explains the 
features of the Pascal Workstation Editor. 

Chapter 5: The Filer 

The Filer is used to store, load, copy, translate and perform other file-related utility operations. This 
chapter details performing these operations with the Filer. 

Chapter 6: The Pascal Compiler 

Once a program has been written with the Editor, this source code must be compiled into object 
code before it can be executed. This chapter explains the operation of the Compiler and the options 
that can be used to modify its operation. The chapter also describes the modular programming 
capability, which is one of the most powerful features of this system. 
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Chapter 7: The Assembler 

This chapter introduces you to the Assembler, which converts programs written in assembly lan- 
guage - a humanly understandable version of the microprocessor's machine language - into object 
code for the MC68000 family of processors used in these HP computers. 

Chapter 8: The Librarian 

This chapter covers using the Librarian. In the system are libraries of object-code modules: some 
consist of device-drivers, while others consist of useful procedures for such applications as I/O and 
graphics. You can also design your own modules. The Librarian's function is to manage libraries of 
Pascal and Assembler object modules. 

Chapter 9: The Debugger 

We all wish that a program would run perfectly the first time. Unfortunately, there is little evidence 
in real life to support that fantasy. The next best thing is to have some good tools to help you debug 
your programs. This chapter explains the debugging features available with this system. 

Technical Reference Appendix 

This appendix contains the following information: 

• A history of the Pascal system, which includes descriptions of the differences between the 3. 1 
and previous versions of the Workstation system. 

• A list of module names used by the 3. 1 system. 

• Software memory map. 

• Tables of available display characters. 

Command Summaries 

This appendix contains a summary of commands for each of the Pascal subsystems. 

Glossary 

Knowing what technical terms mean is always useful. 

Error Messages 

This appendix contains the complete listings of all error messages for the Pascal System and its 
various subsystems. 

Index 

This section contains an index to the topics in both volumes of this manual. 

Previews of Chapters in Volume II 

Here are brief previews of the contents of each of the chapters in the second volume of this book. 

Chapter 10: Overview of Workstation Software Features 

This chapter gives a brief introduction to Workstation Pascal language and library features. It also 
tells where various software features are described in the Workstation Pascal documentation set. 

Chapter 11: Data Types and Structures 

This chapter describes the types of data available in the Workstation Pascal language. It also briefly 
describes some of the data types and structures that are not available with standard Pascal. 
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Chapter 12: Program Flow 

This chapter describes the features of this system which allow you to alter the flow of a program. 

Chapter 13: Numeric Computation 

This chapter describes the standard Pascal numeric data types and how they are implemented in 
this Pascal language. It then shows several examples of useful techniques for dealing with angles, 
rounding, logarithms, number-base conversion, calendars, and pseudo-random numbers. 

Chapter 14: String Manipulation 

This chapter describes how to use the HP Pascal type s t r i n S, as well as using the associated string 
functions and procedures. 

Chapter 15: Programming with Files 

This chapter describes general uses of files, as well as many Workstation-specific file access techni- 
ques. 

Chapter 16: Dynamic Variables and Heap Management 

This chapter describes how to create and use dynamic variables, as well as how to reclaim the 
memory used for these temporary variables. 

Chapter 17: Error Trapping and Simulation 

This chapter describes how to programmatically handle, and possibly correct, errors before they 
halt the execution of your programs. It also shows how to simulate errors in order to debug the 
error-handling portions of your programs. 

Chapter 18: Special Configurations 

This chapter describes how to set up "non-standard" configurations. It first gives background 
information regarding how the system boots and configures itself, and then it describes the steps 
required to set up several configurations. 

Chapter 19: Non-Disc Mass Storage 

Several "non-disc" types of mass storage devices are available on the Pascal Workstation: EPROM 
(Erasable Programmable Read-Only Memory) cards, Magnetic Bubble Memory cards, and DC600 
tape cartridge drives. Configuring and using these devices is described in this chapter. 

Chapter 20: Compatibility and Porting 

This chapter describes the approaches available for running existing Pascal 3.0 software on new 
Series 300 computers with the Pascal 3. 1 system. 

Error Messages 

This appendix is an abbreviation of the lengthier appendix given in Volume I. This listing of errors 
fits on a single sheet of paper, which you may find handy to remove from the manual and place in a 
more convenient place. 

Index 

This volume also has an index to the topics in both volumes of this manual. 
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Introduction 

The Main Command Level is the central point of reference for the operating system. It is "where 
you are" after booting the system and entering the time and date. 

All the Main Command Level commands are listed in the subsequent Quick Reference. However, 
this chapter focuses mainly on those Main Command Level operations which do not call subsys- 
tems (such as the Editor, Filer, Compiler, etc.); the subsystems are each described in later chapters 
of this manual. 



Main Command Prompt 

The Main Command Level consists of two prompt lines, only one of which is displayed at one time. 
Press the f ? ) key to toggle between them. 

Command : Compiler Filer Editor Initialize Librarian Run eXecute Version ? 
Command: Assembler DebuSSer Memvol Newsvsvol Permanent Stream User What ? 

The uppercase letters in the prompt lines indicate which key to press to start the operation. 
All of the operations are available regardless of which prompt is being displayed. 

The prompts are abbreviated on the 50 column display of the Model 226. 

Command: Cmplr Edit File Init Lib r Run Xcut Ver ? 

Command: Asm Db«f Memv New Perm Stream User What ? 

Note 

This manual describes many keyboard operations. Since you can have 
one of three different keyboards, this manual generally describes the 
keystrokes required on all three keyboards. 

For ins tance, on the HP 46020A keyboards, there are both ( Enter ) and 
(Return) keys, w hile on the HP 98203A and 98203B keyboards, there is 
only an (ENTER] key. When you are directed in this m anual t o pr ess one 
of these keys, the text will usually say: "Press the ( Return ) or [ Enter ) 
key." 

Another co mmon example is the (Select ) key on the 46020 and the 
( EXECUTE ) key on the 98203 keyboards. When you ar e directed t o 
press one of these keys, the text will say: "Press the ( Select ] ( ( EXECUTE ) ) 
key." (The second key noted in parentheses is the 98203 key.) 

Descriptions of each keyboard and key-correspondence tables are 
given in the Pascal User's Guide. 
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Main Command Quick Reference 



Command 


Description 


Compiler 


Calls the Compiler to translate Pascal source code 
into object code. 


Editor 


Calls the Editor for creating or editing a source program or textual document. 


Filer 


Calls the Filer for management of the File System. 


Initialize 


Initializes the File System (but not discs). 


Librarian 


Calls the Librarian for managing, linking, or unassembling object-code files. 


Run 


Runs the workfile (compiling it if needed) or the last program compiled since 
power-up. If there is no workfile, Run operates like eXecute. 


eXecute 


Asks for a code file and runs it. 


Version 


Allows setting the time and date, and displays all the current system version 
information. 


Assembler 


Calls the Assembler to translate an Assembler language source program into 
object code. 


Debugger 


Runs a program under control of the Debugger. 


Memory volume 


Sets up a memory resident mass storage volume for fast access. 


New sysvol 


Asks for a volume to be designated as the system volume. 


Permanent 


Asks for a code file to be permanently loaded into memory for execution without 
disc loading each time. 


Stream 


Asks for a stream file whose characters are interpreted as keyboard input until 
there are no more left. 


User restart 


Restarts the last program or subsystem that was run. 


What 


Displays the system file table and allows you to change the system files or system 
and default volumes. 
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Main Command Reference 

Each command in this section contains a description and a syntax diagram. The syntax diagrams 
contain rounded and rectangular boxes. Elements in rounded boxes should be interpreted as 
literals. An example is as follows: 



Cm) 



This notation indicates that you must literally type a ( C ) as part of the command. 

f Imturn ) or (ENTER) \ 

The ( Return ) or ( Enter ) indicates that you can press either key. 

Elements in rectangular boxes are non-literal descriptions of command parameters. An example is 
as follows: 



file 
name 



This notation indicates that you must supply the actual file name as part of the command. 
An example of a complete command is as follows: 



(Oil) » | gg | » ( (»g°r(lB) )-H 



If, for example, this was the Compiler command syntax diagram, it would mean that you must type 
( C ) to run the Compiler, then ty pe the name of the file to be compiled, and enter the file name 
with either the ( Return ) or the ( Enter ) key. 



8 Main Command Level 



eXecute 



The eXecute command runs a specified code file. 



C^^)- Hspeci f Ac e ati nh * ( g^jjjjj ) ~H 



Item 


Description/Default 


Range Restrictions 


file specification 


literal 


Any legal file 

specification (see the File 

System chapter) 



Semantics 

The file you specify should be previously compiled or assembled and ready to run. It is not 
necessary to include the .CODE suffix in the file name; it is automatically appended to the file name 
if not included. If the actual file name does not contain a .CODE suffix, you will need to terminate 
the file specification with a period to suppress this suffix. 

If the specified code file imports other modules, those modules must be contained in the file being 
executed, in the current System Library (which must be on-line), or they must be Permanently 
loaded (by using the Permanent command at the Main Level). You can use the What command to 
see which file is designated as the current System Library, and to change it if desired. 
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Initialize 



The Initialize operation updates Unit Table entries for all units that are currently on-line. (It does not 
initialize mass storage media; that function is performed by using the MEDIAINIT utility program. 
See the Pascal User's Guide for further details. ) 



(q5>h 



Semantics 

The Unit Table contains a record for each of 50 possible logical units available to the File System. 
The assignment of unit numbers to physical devices (auto-configuration) is performed by the 
TABLE program at power-up. Each record contains the "device address vector" of the physical 
device which corresponds to that logical unit number. The computer then looks at the physical 
location indicated by the device address vector to see if the device is on-line. If it is, that fact is 
marked in the record for that unit, along with the volume name (if media is currently installed in the 
device). Afterwards, the computer only looks at the Unit Table to see if a particular device is on-line; 
it does not check the actual device. (See the Booting Process section of the Special Configurations 
chapter for further details of how the TABLE program works.) 

When a device is added to your system after the computer has been powered-up, you will usually 
need to execute BOOT: TABLE or power-up the system again in order for the device to be 
recognized. However, the Initialize command may in some cases be sufficient to get the system to 
recognize the new device. 

Initialize also performs a device clear for all on-line devices and causes the system to forget the last 
loaded file (the User command can't reload the last program). The Initialize operation also causes 
all temporary files to be removed from each volume the next time a file is opened on the volume. 

The volumes CONSOLE: (Unit #2) and PRINTER: (Unit #6) are special cases; these volumes are 
always assumed to be on-line. Thus, the system may "hang" if either of them is off-line. 
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Memory volume 



The Memory volume command creates a mass storage volume in memory. 
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Item 


Description/Default 


Range Restrictions 


unit number 


integer 


7 thru 50 


volume size 


integer indicating the number of 512-byte blocks 


ssl 


directory size 


integer indicating the maximum number of files 
in the volume 


5*1 



Semantics 

The Memvol command gives you the capability for very fast mass storage operations. 

When the Memvol command is given, you are prompted for a unit number. This number corres- 
ponds to an entry in this Unit Table. Don't give a unit number which is already in use. The Volumes 
command in the Filer subsystem shows which unit numbers are currently used. For most applica- 
tions 50 is the recommended unit number to use for your first memory volume. 

You are then prompted for the number of (512-byte) blocks needed for the memory volume. Try 
to estimate conservatively the amount of memory you want reserved for the memory volume 
because it cannot be returned for general purpose use without turning off the computer. On the 
other hand, if you don't specify enough space, you have to create another larger volume. 

Memory volumes are useful for program development where a lot of mass storage I/O (editing and 
compiling) is involved. Reserve enough space on the memory volume for both the source file, the 
object code file, and 40 extra blocks for the Compiler's temporary files. A good rule of thumb is: 

size_of_volume = size_of_source_file (in 512-byte blocks) * 4 + 40 

If you are transferring a source file from disc (as opposed to starting from scratch) you can 
determine its size by getting a directory listing of the volume that contains it. However, note that 
different directories return the file size in different units. 

• LIF directories use 256-byte "blocks" 

• WS1.0 directories use 512-byte "blocks" 

• SRM directories use 1-byte "blocks" 

Note that the default directory access method (DAM) for memory volumes is LIF; this DAM is the 
primary DAM specified in the TABLE program. See the Special Configurations chapter for further 
details about changing the primary DAM. 
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You are then prompted to give the number of directory entries you need for this memory volume. 
Number of directory entries ? 



Type the number you think you'll need and press ( Enter ) . 

You can refer to your memory volume by it's unit number. For example: 

#50: 

Alternately, you can refer to it by its given volume name, which is initially RAM:. For example: 
RAM: 

If you plan to use more than one memory volume, use the Filer's Change command to give 
each memory volume a unique name. 

Here is a method for setting up an extremely fast program development environment. 

1. Create a RAM: volume and specify it as the system volume using the Newsysvol com- 
mand. 

Specify RAM: as the default volume using the Main Command Level's What command 
or the Filer's Prefix command. 

2. Permanently load the Editor and Compiler using the Permanent command. 

3. Go into the Editor and write your program. 

4. When you're ready to leave the Editor, use the Update option to create a workfile. The 
system puts the workfile on the fast RAM system volume. 

5. Press ( R ) . 

Your file will automatically be compiled. If it compiles with no errors, it will be run. If it contains 
errors, you will have the option of returning to the Editor. 



Note 

Since memory volumes are volatile, don't forget to save the files in the 
memory volume on a disc before turning off the computer. 
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New sysvol 



The New sysvol command specifies a new system volume and updates the operating system file 
table accordingly. 
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Item 


Description/Default 


Range Restrictions 


unit number 


integer 


1 thru 50 



Semantics 

The system file table is used in locating operating system files. It contains the volume and file names 
of system files (EDITOR, FILER, etc.). W hen yo u press a key at the Main Command Level that 
invokes one of these subsystems (such as ( E ) ), the system attempts to load the corresponding 
file indicated in the system file table (here, the EDITOR file). 

You can use this command to specify a new system volume. The first step in this operation prompts 
you for a unit number. The device corresponding to the specified unit number is considered to be 
the new system volume, and serves as a starting point in the search for the system files: 
ASSEMBLER, COMPILER, EDITOR, FILER, LIBRARIAN, LIBRARY, and the work file. If any of 
these system files are not found, the Unit Table is used in a sequential search for the rest of them. As 
each file is found, the name of the volume on which it is found is prepended to the file name (for 
instance, SYSVOL:LIBRARY), and the complete file specification is placed in the file table. If any 
system file is not found in this search, the operating system assumes that it will find the file on the 
flexible disc volume on which it was delivered (for instance, ACCESS:EDITOR). 

Use the Main Command Level's What command to see the resultant system file table. 
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Permanent 



The Permanent command loads a program permanently into memory. 

eciVi^ationl -" ^ CIS °r (jjlJ -H 



Item 


Description/Default 


Range Restrictions 


file specification 


literal 


Any legal file 

specification (see the File 

System chapter) 



Semantics 

The Permanent command can be used to load a user program, a system program (Editor, Compiler 
etc.), or a module that is needed by a program. This code file is then ready to execute immediately 
when the command is given. A "P-loaded" (Permanently loaded) program does not have to be 
loaded from disc each time it is run. 

After you give the Permanent command, you are prompted for the name of the file which contains 
the module or program. You need not include the .CODE suffix; if you don't include one, the suffix 
will be appended to the file name. If the file to be P-loaded does not have a .CODE suffix, end the 
file specification with a period to suppress the suffix from being appended to the file name automati- 
cally. 

Several programs may be P-loaded in memory. The operating system keeps track of which prog- 
rams have been P-loaded. When you give a command to run a program, the operating system 
checks to see if it has been P-loaded; if so, it is executed immediately. If not, it is loaded from disc 
and then executed; after execution, the memory used by the program is reclaimed. 

An object module which is imported by a program must be in the object file that contains the 
program, in a file previously P-loaded, or contained in the current System Library (which must be 
on-line). 

A program or module's global variables are zeroed only when it is loaded, not each time the 
program is run. However, note that neither local variables nor dynamic variables are zeroed. 

Note 

Th volume name is not retained when a file is P-loaded. Attempting to 
execute a file of the same name but on a different volume will still result 
in the P-loaded file being executed. 

For SRM users, do not use a directory path name to execute a P-loaded file. 
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Run 



The Run operation causes the workfile or last compiled program to be executed. 
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Item 


Description/Default 


Range Restrictions 


file specification 


literal 


Any legal file 

specification (see the File 

System chapter) 



Semantics 

When the Run command is given, the operating system checks to see if there is a workfile. If there is 
a CODE workfile, it is executed; if not, the most recently compiled or assembled file is executed. If 
there is a TEXT workfile but no CODE workfile, the TEXT workfile is first compiled (with the system 
compiler) to a CODE file and then the CODE file is executed. If there is no workfile or previously 
compiled program, the command operates like the eXecute command and you are prompted for a 
file specification. 



Main Command Level 15 



Stream 



The Stream command "executes" a file of ASCII characters as if they were being typed from the 
keyboard. 
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Item 


Description/Default 


Range Restrictions 


file specification 


literal 


Any legal file 

specification (see the File 

System chapter) 



Semantics 

A command stream or stream file is a file that is interpreted as input to the Main Command Level 
and/or its subsystems in place of keyboard input. The Stream operation causes a file to be inter- 
preted. Therefore, a stream file is useful for executing a sequence of commonly used commands 
without requiring any operator intervention. 

A stream file is created with the Editor and may be of type ".TEXT", ".ASC" or Data. If you do not 
specify a suffix, a ".TEXT" is automatically appended to the file name; if the name of the file to be 
streamed does not have a suffix, add a trailing period to the file name to suppress the suffix. 

In order to generate a valid sequence of keystrokes, you should first run through the desired 
sequence while noting the keystrokes entered. Note particularly the occurences or absences of the 
[Return] or f Enter ] key. Then enter the same keystrokes in your stream file. If, during an Editor or 
Filer command sequence, you encounter an unpredictable question that has a (Y/N) or (R/O/N) 
question associated with it, do not answer the question in the stream file. These kinds of questions 
are answered automatically as the file is streamed. (Y/N) questions (Yes/No) are answered "Y". 
(R/O/N) questions (Remove/Overwrite/Neither) are automatically answered "R". 

After all the characters in a stream file have been interpreted, control is returned to the keyboard. 

Comments 

Stream files may contain comments. A line beginning with an asterisk (*) will be interpreted as a 
comment if it occurs at the Main Command Level. (Comments cannot be embedded among 
commands for subsystems or user programs. ) When the command interpreter encounters one or 
more comment lines while streaming, they are displayed briefly on the screen, thus allowing the 
process to be monitored. 
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Immediate Execute Keys 

If it is n ecessary t o us e keys tha t also act as immediate-execute commands in the Editor, such as 
( Select ) ( ( EXECUTE ) ) or ( Backspace ) , use the following key sequences to generate those keystrokes. 



Immediate-Execute Key 


Generate with these Keys 


( Return ) 


( CTRL )-( Select ) ( M ) 


( Select ] 


( CTRL )-[ Select ) ( C ) 


[Backspace] 


( CTRL )-( Select ) [ H ) 


( Tab ) 


( CTRL )-( Select ) ( 1 ) 


( Clear display ] 


( CTRL )-( Select ] ( L ] 


Left arrow 


( CTRL ]-[ Select ) ( H ) 


Right arrow 


( CTRL ]-( Select ] ( < ) 


Up arrow 


( CTRL )-( Select ] ( ? ) 


Down arrow 


( CTRL )-( Select ) ( J ) 



If you have a 98203 keyboard, substitute ( EXECUTE ) or ( EXEC ) for ( Select ) in the preceding table. 

Prompts for Keyboard Input 

A stream file can be made to display a prompt on the console and then wait for an input string from 
the keyboard. The input string is assigned to a variable in the stream file. When the variable is 
encountered during streaming, the string is used in its place. 

This input prompting must appear in the stream file before all of the commands or comments. Up to 
36 prompts are allowed. They are denoted with an " = " as the first character on a line. 

To prompt for an input string, place an equal sign, followed by a single alphanumeric character 
variable name (uppercase and lowercase letters used for variables are treated as equal), followed by 
the prompt text. For example: 

= f What is the name of the file to be P-loaded ? 

When the file name is typed in response to the prompt, it is stored in the specified variable, in this 
case the variable named f. 

After the input prompting, begin entering the commands in the stream file. When you want the 
input string to be given to the operating system, use the variable preceded by "@". For example, 
the following characters are a command stream: 

p@f 

The command is the Permanent load command with a file name parameter indicating which file is 
to be P-loaded. The file whose name was given in response to the above prompt is then P-loaded. 
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Disabling the Prompt Feature 

If the stream file name contains a C * 3 specifier, the ability to prompt for keyboard input is disabled. 

(Normally when a file is Streamed, the file is copied to the file named STREAM on the current 
system volume; during this copy, prompts are displayed and @ variables assigned values input 
from the keyboard by the computer operator. After all variables have been assigned, the file is read 
as keystrokes; in other words, *STREAM is the file that is actually streamed. The C * 3 suppresses 
the normal processing of the prompts and input variables, as the keys are read directly from the 
specified file. ) 

Stream Files on Read-Only Devices 

It is the disabled-prompt mechanism (see preceding discussion) that allows the use of stream files 
stored on read-only mass storage, such as EPROM, and the use of read-only devices as system 
volumes. This mechanism is also used to process the AUTOKEYS stream file, if found during the 
boot process when the AUTOSTART stream file is not present. For examples of AUTOSTART and 
AUTOKEYS stream files, see the discussions in the Pascal User's Guide and in the Special Con- 
figurations chapter of this manual. 
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User restart 

The User restart command causes the last program that was run to be rerun. 

Semantics 

Included in the meaning of "program" are user programs and operating system programs such as 
Editor, Filer, Compiler, etc. 

Global variables are zeroed at the time a program is loaded, not each time a program is rerun. 
However, note that neither local variables nor dynamic variables are zeroed. 
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Version 



The Version operation allows you to change the system time and date. 
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Item 


Description/Default 


Range Restrictions 


day 




integer 


1 thru 31 


month 




three alpha characters; letter case is ignored 


Jan, Feb, Mar, Apr, May, 

Jun, Jul, Aug, Sep, Oct, 

Nov, Dec 


year 




integer 


thru 99 


hour 




integer 


thru 23 


minutes 




integer 


thru 59 


seconds 




integer 


thru 59 


separator 




non alphanumeric character 


:,-,/, space, etc. 



Semantics 

In addition to prompting for the system time and date, some operating system information is 
displayed. The current operating system revision, available global and user memory space informa- 
tion is displayed. Also, default and system volume information is displayed. 
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The Version Prompt 



New system date ? 

System date is 
Clock time is 

Workstation 



1-Jun-B4 
14:14:50 



Rev 



3.0 15-APT-84 



Available Global Space 579G0 bytes 
Total Available Memory 191042 bytes 



System volume 
Default vol u m e 



SYSOOL: 
SYSUOL: 



Copyright 1984 Hewlett-Packard Company. 
All rights are reserved. Copy in 3" or other 
reproduction of this program except for archival 
purposes is prohibited without the prior 
written consent of Hewlett-Packard Company. 



For more details on "Global Space", see the Compiler chapter. 



Main Command Level 21 



What 



The What command displays the "system file table" and allows you to specify new file specifica- 
tions for the system files. 
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Item 


Description/Default 


Range Restrictions 


file specification 


literal 


any legal file specification 

(see the File System 

chapter) 


volume sp 


ecification 




literal 




any legal volume 

specification (see the File 

System chapter) 



Semantics 

The system file table contains file specifications that are used by the operating system when locating 
system files (Assembler, Compiler, Editor, Filer, Librarian, Library, and Default and System 
volumes). The What command displays the system file table; a typical example is shown below. 
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The What Display 



Assembler Compiler Editor Filer Librarian 
liBrarv System volume Default volume Quit 



ASSEMBLER 

COMPILER 

EDITOR 

FILER 

LIBRARIAN 

LIBRARY 



SYSVOL: 
SYSUOL: 
SYSUOL: 
SYSYOL: 
SYSUOL: 
SYSVOL: 



* System volume: 
: Default volume: 



: ASSEMBLER 
iCOMPILER 
: EDITOR 
;FILER 
LIBRARIAN 
LIBRARY 

SYSVQL: 

SYSUOL: 



Typing one of the uppercase letters at the top of the menu allows you to change the corresponding 
file specification for that system file. 



Note 

When specifying a system file name that does not have a .CODE suffix, 
use a period at the end of the file name to prevent a .CODE suffix from 
being appended to the file name. 

With this command, it is possible to do such things as specify a file other than LIBRARY as the 
System Library or your cus tom gr aphics editor as the System Editor. In the case of your custom 
editor, you need only press ( E ) to invoke it. 

Specifying a logical unit number, such as #3 : , as the Default volume allows any disc media in a unit 
with removable media to be the desired volume. To subsequently specify any volume in the default 
unit, only t he file name need be specified. To accomplish this, make sure that the drive door is 
open, type ( D ) for a Default volume change, and then type the following: 



*3: ( Enter ) 
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Chapter 



Introduction 

This chapter introduces you to the Workstation Pascal File System. The File System organizes and 
accesses information which is stored on mass storage devices. Even if you are an experienced 
programmer, you should read this material because it will help you understand the features of your 
Pascal workstation. 

Primary vs. Secondary Storage 

Your computer has built into it a substantial amount of very high speed memory called Random 
Access Memory, or RAM. This memory is called primary storage to distinguish it from external 
mass storage, also called secondary storage. Normally, data processed by the computer must first 
be placed in internal memory. (The term "data" is used broadly to mean any information proces- 
sed by the computer, so programs are data, too. ) 

RAM has three important characteristics: 

• RAM is very fast: Some data items can be stored or retrieved from RAM in less than a millionth 
of a second. 

• RAM is volatile: Data in RAM is lost when the computer is powered off. 

• It is expensive compared to alternative, slower forms of data storage, such as discs or magnetic 
tape. 

Information not immediately needed by the computer is kept in secondary storage. Some impor- 
tant characteristics of magnetic discs are listed below: 

• Data access is slow compared to RAM, often as much as ten thousand times slower. 

• The data is relatively permanent; that is, it is available until erased. 

• Magnetic storage is inexpensive compared to RAM. 

• Magnetic media are often removable and replaceable, providing an almost unlimited amount 
of long-term storage. 



24 The File System 



Pascal Volumes 

Let's take an exploratory trip, using the computer itself to investigate the file system. You 
should already know how to load the Pascal Language system, and be aware of its various 
subsystems, such as the Editor and Filer. 

To begin our journey, begin at the Main Command and load the Filer subsystem by pressing: 

CO 

The Filer is located on the Pascal disc labelled ACCESS:. When the Filer's prompt line appears, 
execute the Volumes command by pressing: 



olumes 


on-line 


1 




CONSOLE 


n 




SYSTERM 


3 


t 


BOOT: 


4 


8 


WRKING: 


G 




PRINTER 


11 


* 


SYSVOL: 


12 


* 


MYVOL: 


13 


# 


MASTER: 


14 


tt 


via: 


50 


* 


RAM: 



The various disc drives connected to your computer will be accessed and then you will see a 
display similar to the following: 

This is your workstation's CRT display. 
This is your workstation's keyboard. 
BOOT: disc is in right-hand drive (of 9836). 
Initialized disc with volume name WRKING: 
Printer is connected to built-in HP-IB. 
The * indicates the system volume. 
(Volumes 11 through 14 are examples of a 
possible HP 9133A disc drive configuration.) 

Ram volume made with Memory Volume command. 
Prefix is - MY VOL: MYVOL: is current prefix volume. 

Precisely what will be displayed depends on what peripherals are connected to your computer 
and what discs are currently installed in the disc peripherals. Note how your display appears. 
You may want to change some of the discs in your systems disc drives or turn off a peripheral 
and see how that changes the display. 

Volumes 

The word "volume" was chosen by analogy to a book. Volume denotes a logical entity in which 
a substantial amount of information can be stored. For instance, a flexible disc is a volume. 
Volumes have names by which we may refer to them. The display above shows what volumes 
are currently accessible to the file system on my system. 

Notice that each volume name is followed by a colon. This convention is used throughout the 
Pascal system. The colon is a delimiter or punctuation mark which separates the volume name 
from further information used to designate data within the volume. 

A single large disc may contain more than one volume, as a shelf can hold more than one book. 
Flexible discs contain a single volume. For flexible discs we may use the volume name as the 
disc drive's name. By that I mean, if we refer to the volume BOOT : by name, the computer will 
find it in whichever drive it is located. 



The File System 25 



Note 

Because the file system works with named volumes, it is very impor- 
tant not to have more than one volume of a given name on-line at 
one time. The file system may destroy data by using one volume 
when you meant the other. 

You can see that some of the volume names don't correspond to any disc device at all. Actually 
the file system has a name for each input/output device. SYSTERM: is the name of the 
keyboard volume, CONSOLE: is the name of the CRT, and PRINTER: is the name of the 
system hard copy device. We will have more to say about these non-disc volumes later. 

Logical Units 

The numbers in the column to the left of the Volume names displayed above are called "logical 
unit numbers" or simply "units". The volume name denotes a particular disc, while the unit 
number denotes a particular location for a volume. In the case of flexible discs, the unit number 
corresponds to a physical disc drive. In the case of a large fixed disc which is divided into several 
logical volumes, each logical unit represents a portion of the disc surface which is treated as if it 
were a separate physical disc drive. 

To refer to a unit instead of a volume, use a # followed by the unit number. For instance #3 : 
and BOOT : both refer to the same volume as long as BOOT: is installed in the right-hand disc 
drive of a Model 226 or Model 236 computer. 

Drive Numbers vs. Unit Numbers 

Since a single machine can contain two or more drives, you need to be able to distinguish 
between them. If you read the machine's manual, you will find that the drives are differentiated 
by drive number. For instance, the right-hand floppy drive in a 9836 is drive number 0, while 
the left-hand drive is drive number 1. The File System distinguishes between them by assigning 
each a unique logical unit number. In the case of the 9836, these drives are normally assigned 
unit numbers 3 and 4, respectively. With external dual floppy drives, drive is usually the 
left-hand drive, while drive 1 is the right-hand drive. And with hard disc drives, there can be 
several drive numbers. Don't be alarmed, however, because the system takes care of the 
correspondence between drive numbers and unit numbers for you. In addition, this manual 
refers almost solely to logical unit numbers, not drive numbers. Drive numbers were mentioned 
so that you would realize that they are not the same as unit numbers. 

Blocked and Unblocked Units 

Some of the units are displayed with # or * between the unit number and the volume name. 
These are blocked units. Blocked units are memory devices that are divided into sectors 
(blocks) and have directories describing their contents. 

We aren't yet ready to talk about the data stored in a volume, but you probably won't be 
surprised to learn that it is organized into groups called "files", which are like chapters in a 
book. The directory of a blocked volume is essentially a table of contents. 

The other units are unblocked or "byte stream" devices (such as the printer, keyboard, and 
CRT). Unblocked devices process information one character at a time and do not have direc- 
tories. 
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The System Volume and Default Volume 

Although your workstation can deal with many volumes (up to 50 on-line at once), there are 
two volumes which are referred to so frequently that special abbreviations have been provided 
to name them. They are the system volume and the default volume. 

The System Volume 

The system volume is used by the Operating System to store its own private files and records. 
Since the Operating System is always overseeing your computer's operation, the system 
volume needs to be accessible practically all of the time. The abbreviated name for the system 
volume is * (asterisk), which appears next to the system volume in the Volumes command's 
display. The asterisk need not be followed by a colon, since it is distinctive. Thus for the Volume 
display shown previously, these notations all denote the system volume: 

* 
*: 

SYSUOL: 
*11 : 

Here are some of the ways the operating system uses the system volume: 

• When the Operating System is loaded and begins to function, it looks on the system 
volume for subsystem programs such as the Editor, Filer and Compiler. If these subsystem 
programs are on other volumes, the Operating System will still find them. 

• When the Operating System first begins to function, it looks on the system volume to find 
the system date. The system date is put on all files as they are created to help in maintain- 
ing file organization. If you change the system date, the new date gets written on the 
system volume. 

• During processing of a stream file, data may be temporarily stored on the system volume. 
A stream file is a pre-recorded sequence of keystrokes which are treated as if they came 
directly from the keyboard. 

• If you create an anonymous file (see the Programming With Files section), it will be stored 
on the system volume. An anonymous file is a file created by a program, used by the 
program, and then destroyed when the program ends. While the program is in existence, 
the anonymous file is for all purposes a real file. 

• If you use a work file during development of a program, it will be stored on the system 
volume. 

• If you use an AUTOSTART or AUTOKEYS file, it must be stored on the system volume. 

The Default (Prefix) Volume 

The other special volume is the default volume. This volume is sometime called the prefix 
volume. In many applications it is most convenient to have the frequently needed files together 
in a single volume. If these files are being accessed frequently, it is tedious to constantly type the 
volume name or unit number. You can instead tell the system that when no volume name is 
specified, the one to use is the default volume. You specify the default volume by using the 
Filer's Prefix command. 
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The preceding Volumes display indicates "Prefix is - MYVOL:". This means that MYVOL: is the 
default volume. The default volume can be specified in two ways. If a colon separator appears 
with no volume name before it, the default volume is assumed. If a file name is given with no 
volume name before it, the default volume is assumed. 

Use the Filer's Prefix command to set the default volume name: 

m 

Prefix to what directory? 
SYSVOL: (Return) or (ENTER) 
Prefix is SYSVOL: 

The default volume and the system volume can be the same volume. In fact, except for single 
drive configurations, the default condition you received from the factory has SYSVOL: as both 
the default and system volume. 

If a unit specified by unit number (e.g. #3:) in a Prefix command does not contain a disc when 
the Prefix command is executed, that unit becomes the default volume. That means that the 
current disc in that drive, no matter which disc is the current disc, is the default disc as long as it 
is in the drive. 

You can also set the default volume name using the What command of the Main Command Level. 
The What command is more powerful than the Prefix command because What allows you to 
specify a new system volume, as well as the name and location of each of the system files (Filer, 
Editor, Library, etc). For further information on the What command, see the "Main Command 
Level" chapter of this manual. 

Files 

Information within a blocked volume is further organized into files. A file is a collection of 
related information, having a name by which it is identified during the file operations. Since a 
volume usually contains many files, within the volume there is also a directory, or "table of 
contents," telling the name of each file, how big it is, what sectors it occupies on the disc, and 
(roughly) what sort of data it contains. 

Files are created by computer programs - either system programs (such as the Editor, Filer and 
Compiler, ) or user application programs. 

For example, when you save a Pascal program written with the Editor, the program is saved 
with the specified file name in either the current default volume or the specified volume. When 
that same program is compiled, the object code is stored in another file. When the object code 
program is executed, it may create more files. 

You can use the Filer to list the files in a volume. For instance, to see what is in the default 
volume of our example system, type: 

m 

to invoke the Filer's List directory command. The Filer responds with: 
List what directory? 
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When a volume is not specified, the default volume is assumed. To specify the default direc- 
tory, type in: 



( : ) ( Return"! or [ENTER] 

Assuming the configuration shown on previous page, you could have done the same job by 
typing: 

SYSvTJL: ( Return ) or (ENTER) 
The listing of the default volume's directory is shown below. 



SYSVOL: Directory type = LIF leuel 1 

created 9-Au*-82 21.13.37 block size=25G 

changed 9-Au*-82 21.13.37 Storage order 

...file name.... * blKs * bytes last chns 



TAPEBKUP.CODE 


5a 


13824 


2B-0ct-82 


FILEINTRO.TEXT 


64 


1G384 


2B-0ct-82 


FILEINTRO.ASC 


73 


18BB8 


28-0ct-82 


DATAFILE 


10 


2580 


28-0ct-82 



FILES shown=4 allocated=4 unal 1 ocat ed=7G 

BLOCKS (258 bytes) used=201 unused=4499 larsfest space=4493 



File Naming Conventions 

The definition of HP Pascal tries to minimize the work of moving Pascal programs from one 
operating system to another by requiring the use of string values to specify the names of files 
and certain other information such as passwords and access rights. 

In Pascal 2.0 and later versions, the allowable syntax of a file name depends on the type of 
directory in which the file resides. The underlying file support is structured to allow programs to 
work properly regardless of the directory organization(s) being used, but the syntax of file 
names is defined by the type of directory on the volume. 

File Specifications and File Names 

There is a difference between a file specification and a file name. A file name is a character 
string which is the external identifier by which a file is designated in a disc directory. A file 
specification is a character string which consists of the file name and several other optional 
items: volume_id, directory_path, passwords, and size_specifier. Not all of these items are 
allowed by every Directory Access Method or under all circumstances; for instance, directory 
paths and passwords are only used with the Shared Resource Management System's hier- 
archical directory organization. 
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Syntax of a File Specification 

The syntax of a legal file specification is given by the following diagram: 

file-specification :: = [volume_id] [directory_path] file_name ["["size_spec"]"] 

:: = volume_id 

In this notation, items between square brackets [ and ] are optional; quoted items appear 
literally. The definition just given means that a file_spec (file specification) may appear in one of 
two forms. The first form consists of an optional volume_id followed by a colon, then an 
optional directory _path, then a file_name which is not optional, then an optional size_spec. The 
second form consists just of a volume_id. 



Examples of the first form are as follows: 



Fi 1 e_x 

A49ZBC10] 

«4: LIBRARY, 

B00T:SYSTEM_P 

*45:SYSTEM21/FILER 

♦EDITOR. 



Examples of the second form are as follows: 

BOOT: 

«3: 

* 

#45:SYSTEM21/T00LS 
#45: 

Syntax of a Volume Identifier 

The volume_id selects one of up to 50 logical units known to the file system. If no volume_id is 
present, the volume used is the "default volume" selected by the Filer's Prefix command. 
Otherwise, the volume is specified in one of two ways: 

volume_id :: = "#" integer [ password ] ":" 

:: = name [ password ] ":" 

In the first case, the integer is a two-digit number from one to fifty; for example, #23: is a 
volume_id. In the second case, the name is a sequence of characters. The length of the name 
and allowable characters depend on the particular directory organization used by the logical 
unit. For mass storage devices, the volume name is actually stored on the disc itself so it can be 
identified whenever it is inserted into a drive. For devices which have no directory, such as 
printers, the volume name is an arbitrary one supplied by the TABLE configuration program at 
boot-up time. 
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Example volume_ids of the second form are MYSYS: and PRINTER: Volume_ids may be 6 
characters long in LIF directories, 7 characters long in Workstation 1.0 (UCSD-compatible) 
directories, and 16 characters long in SRM directories. LIF and SRM allow lowercase letters, 
while WS-1.0 and unblocked devices ignore letter case. WS1.0 converts all characters to upper- 
case automatically. 

In the case of a logical unit connected to a Shared Resource Management System, the 
volume_id takes a special meaning. The notation #5: refers to the current working directory of 
unit number five; the notation #5:/ refers to the root directory of the SRM with which unit 
number five is associated. The current working directory for any SRM volume is selected by the 
Filer's Prefix or Unit commands, or the What command of the Main Command level. 

On the other hand, if the logical unit does not have a hierarchical directory, then the two 
volume_id notations (e.g., #11: and SYSVOL:) have the same meaning. This is the case for all 
local mass storage devices. 

Syntax of a Directory Path (SRM) 

Directory paths are only allowed when specifying files on SRM logical units. The syntax for a 

directory_path is: 

directory_path ::=["/"]{ directory_name [password] "/" } 
password :: = "<" word ">" 



directory _name 



: = file_name 



a 11 



The use of curly braces "{" and "}" indicates that the information between them may occur 
zero or more times. As you can see, there are two special directory names allowed with the 
SRM. The name "." (a single period) refers to the current directory somewhere along a path to 
a file of an SRM logical unit. The name ".." refers to the parent of the current directory. Other 
file names occuring in a directory path are directories along the path to the one which contains 
the file being specified. 

Passwords are sequences of up to 16 characters, which govern the access rights to a file or 
directory. They are given to a file either at creation time or by use of the Filer's Access 
command. 

Note that a directory path doesn't appear by itself; it appears as part of a file specification, with 
the file name after the directory path. Examples of directory paths are: 

/.<PASS1>/ Denotes root, using password "PASS1". 

/USERS/ROGER/ Denotes directory ROGER in USERS, which is in root directory. 

HERE/THERE/ Denotes directory THERE, found in HERE. 

.. /THERE <PASS2>/ Directory THERE, found in the parent of the current working 

directory. 
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A directory path together with a volume_id might appear as follows: 
#5:/WORKSTATIONS/SYSTEM13/ 

Occasionally there is need for a volume password, which is a case not covered by the above 
syntax. You may use either of the following forms: 

#5 < volpassword > : /dirname l/dirname2/filename 
# 5 : < volpassword > /dirname 1 /dirname2/f ilename 

That is, the volume password may either immediately precede or follow the colon separator. 

Syntax of File Names 

To the Pascal Workstation System, a file name is just a sequence of characters. The Directory 
Access Methods allow all printable characters. However, the following characters have signifi- 
cance either in Filer commands or in the overall specification of files under various Directory 
Access Methods (such as directory paths in hierarchical directories), and therefore should be 
avoided in file names: 

• sharp '#' 

• asterisk '*' 

• comma ',' 

• colon ':' 

• equals ' = ' 

• question mark '?' 

• left bracket '[' 

• right bracket ']' 

• dollar sign '$' 

• less than '<' 

• greater than '>' 

Control characters (ASCII ordinal value less than 32) and blanks are removed by the File 
System before the name is ever presented to any Directory Access Method. 

File Types Derived from File Names 

The type of a file is determined when it is created, and is derived from a suffix (the last 
characters of the file name). Once the file type is determined, a type code is recorded in the 
directory, and changing the file name won't change its type. 



Suffix 


File type 


.ASC 


LIF ASCII text file 


.TEXT 


WS 1.0 / UCSD compatible text file 


.CODE 


Pascal 2.0 object code 


.BAD 


File covering bad area of disc 


.SYSTM 


Boot image file 


No Suffix 


"Data" file 
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File Names (LIF) 

The LIF Directory Access Method (DAM) generally allows any ASCII character to be used in a 
file name. This is contrary to the HP LIF Standard, which states that file names must be 
composed only of upper-case letters, digits, and the underscore '_' character. Note that upper 
and lower case letters are distinct. File names stored in LIF directories are always exactly 10 
characters. 

The LIF DAM recognizes only upper case suffixes. 

The 10-character file name length would be a very severe restriction when four or five charac- 
ters are required for a suffix. To ease this problem, the LIF DAM performs a transformation on 
the file name which compresses the suffix if one is present. The transformation occurs automati- 
cally when a LIF directory entry is made, and it is reversed automatically before the file name is 
ever presented to any program or to the user. 

This process is usually completely transparent to the Pascal user, although its effects may be 
seen when a LIF directory is examined from the BASIC language system. It sounds complicated 
and dangerous, but in practice it is very smooth. Most people would never notice it if they 
weren't told. 

Here is how the LIF DAM changes a name before putting it into the directory. 

1. Look for a standard suffix (for example, ".ASC"). 

a. If a suffix is found, the suffix characters are removed from the name, leaving a trailing 
period. If this name is longer than 10 characters, including the period, then an error 
is reported. 

b. If no suffix is found, and the file name contains less than 10 characters, the file is 
assumed to be a Data file and the name is put into the directory unchanged. If no 
suffix is found, but the file name is exactly 10 characters in length and the last 
character is an A, B, C, S, or T, then an error is reported. 

2. If the file is not a Data file and no error has been reported, the dot is replaced by the first 
letter of the suffix; for instance, the .ASC suffix is replaced by A. If the name is now less 
than 10 characters long, it is extended to a length of 10 characters by appending under- 
score characters (_) to the name. 

Using this algorithm, we would have the following examples: 
File name Translated name 



'A. ASC 


'AA 


'charlie' 


'charlie ' 


'123456789.TEXT' 


'123456789T' 


'GollyGeeeT' 


rejected because it would be 




confused with transformation of 




'GollyGeee.TEXT' 
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The reverse transformation is fairly obvious: 

1. If the 10th character is a blank, do nothing; otherwise, 

2. Remove all trailing underscores. 

3. Compare the last non-underscore to the first letter of each valid suffix. If a match is 
found, remove that letter from the file name and append a dot '.' followed by the full 
suffix. 

4. If no suffix match is found, use the original file name. 

File Names (Workstation 1.0 Directory) 

The Workstation 1.0 (UCSD compatible) DAM allows file names of up to 15 characters includ- 
ing the suffix. Any lower-case letters are transformed to upper-case, so that 'a. text' and 
'A. TEXT' denote the same file. 

File Names (SRM System) 

The SRM itself allows almost any file name. The Pascal system removes blanks and control 
characters from file names. 

However, the Pascal SRM Directory Access Method takes the "<" character to denote the 
beginning of a password. All characters up to the next ">" character are part of the password, 
so that <<<<<<<<> is a (poorly chosen) password. Passwords may be up to 16 characters 
long. 

File Size Specification 

The last, optional part of a file specification is the file size specifier. If present, its syntax is 

size_spec ::= "[" integer "]" 
• • = "r*i" 

This specification only takes effect if a new file is being created with REWRITE, OPEN,APPEND 
or APPEND with OPEN . If the file already exists, the file system tries to make it at least the size 
specified. The size is ignored for RESET. 

In the first form, the integer gives the number of 512-byte blocks to be allocated to the file. For 
instance [100] would cause allocation of 51 200 bytes. 

The second form [*] specifies that the file is to be allocated either (half of the largest free space) 
or (the second largest free space), whichever is larger. 

If no size specifier is present when space for a new file is being allocated, the largest free area is 
assigned to the file. 

For files stored in the SRM, the first extent allocated to the file will be contiguous and of the size 
specified if possible. 
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Several Directory Organizations Allowed 

HP L1F (Logical Interchange Format) is the default directory format used by your Pascal 
Language System. There are many (mutually incompatible) ways to organize files and director- 
ies on a disc. LIF is an HP standard disc organization used to transport files between computers 
made by Hewlett Packard Company. The HP Series 200 BASIC Language System also sup- 
ports the LIF directory structure on your Series 200 computers. 

In addition, your Pascal workstation understands two other disc directory organizations. The 
WS1.0 format was the primary disc directory format used by the Pascal 1.0 Language System. 
You Pascal workstation also supports the hierarchical directory structure used by the Shared 
Resource Management System. The SRM and hierarchical directories are discussed as a sepa- 
rate topic later in this section. The WS1.0 format is compatible with the widely used UCSD* 
Pascal system. 

File Name Suffixes and File Types 

Here are four examples of legal file names: 

FILEINTR0.ASC 
FILE INTRO. TEXT 
TAPEBKUP.C0DE 
DATAFILE 

The first three file names have a suffix. This suffix is part of the file name, so file INTRO, asc and 
F I LE I NTR0 . TEXT are different files. The suffix was appended to specify the file type when the file was 
created. The file type is stored in the directory along with the file name. Thus, the file type would 
not be changed if you later changed the file name by removing or modifying the suffix. You can see 
the file type of each file by listing the directory using the Filer's Extended Directory List command. 

The suffixes recognized by the Pascal 2.0 File System (and later versions) are shown below: 

.ASC These files are HP Logical Interchange Format (LIF) ASCII files. It is intended to 

be the method for interchanging data files among various HP computers. In- 
formation stored in a .ASC file is stored as individual logical records. Each record 
has a two-byte length header and contains an even number of bytes. (A pad 
character is added, if necessary, to make an even number of bytes. ) 

.TEXT Text files are the default type of file produced by the Editor. They follow the 

WS1.0 (UCSD-compatible) format, .text files consist of a 1024-byte header 
containing Editor environment information, followed by compacted text in 1024- 
byte pages. Each line of information with more than one leading blank begins 
with a Data Link Escape control character (DLE, ASCII code 16). This character 
is followed by a one-byte "indentation" code; its binary value is calculated by 
adding 32 to the number of initial blank characters in the line. (Lines with zero or 
one leading blank merely put the actual line there; there is no DLE/leading 
blanks compression. ) Each line is then terminated by a Carriage-Return control 
character (ASCII code 13). If a line will not fit at the end of a 1024-byte page, 
then the whole line is moved to the beginning of the next page, and the remain- 
der of the previous page is padded with ASCII nulls (ch r ( o ) ). 
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.CODE A .CODE file is the object code produced by the Compiler, Assembler, or Libra- 

rian. This file is also called a library. 

.SYSTM A.SYSTMfileisa special file recognized by the Boot ROM as a file containing an 

operating system (a "system Boot file"). 

.BAD A . BAD file is used as a permanently cover failed disc sectors. Use the Filer's Make 

command to make a file of type .BAD over the defective sector of the disc media. 
This type of file should only be used as an emergency measure, until the defec- 
tive disc can be replaced. 

(no suffix) A file whose name at the time of creation does not end in one of these suffixes is 

said to be of type Data. 

The Pascal operating system utility programs (e.g., Editor, Filer), in many circumstances, automati- 
cally append the appropriate default suffix to a file's name. (Note that the only time the Filer 
appends a suffix is in the G e t and Save commands. ) For instance, when loading a file into the Editor, 
just type the file name without a suffix. The Editor assumes that in normal circumstances you will 
want to edit a .TEXT file and will automatically add the suffix. Of course, if you wish or need to 
specify a suffix, you may. For instance, if you want the Editor to load another type of file, then the 
correct suffix must be specified. If the file has no suffix, place a period at the end of the file name. 
The period stops the Editor from adding the .TEXT suffix. If you try to specify a file type that the 
subsystem can't work with, such as a . CODE file in the Editor, you may get various kinds of probably 
undesirable results. In this example, depending on how you access the file and the mass storage 
device used, you could get an error message reading "Illegal I/O request", a 
"No workfile found" message, or myriad empty lines. 

Automatic suffixing is very convenient. For instance, you might write a program with the Editor and 
call the output file WORK. The Editor automatically appends .TEXT. When you use the Compiler to 
compile WORK, the compiler automatically appends . TEXT to the source file name, and . CODE to the 
output file name. Although there are two files, you only need to remember one name. To execute 
WORK .CODE, you need only type the following (from the Main Command Level): 



fSeiecD WORK (jtobim) 
or 

( EXECUTE"] WORK (ENTER) 

Suppressing the Suffix 

On the other hand, you may wish a file name which has no suffix. You can suppress the automatic 
appending of a suffix by typing a period as the last character in the file name. For instance, to create 
a file of type Data with the name AFILE, just tell the Editor to save your file as "AFILE.". The period 
suppresses the default .TEXT suffix and implicitly directs the Editor to create a file of type Data. 
Likewise, the Librarian and Compiler will automatically append . TEXT or . CODE to file names unless 
you tell them not to with the period. 
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System programs like the Editor don't have the .code suffix attached to their file names. This 
protects them against accidental destruction by a wildcard purge operation on all .CODE files. If you 
wish to permanently load a system program (which have no suffix) into memory with the Perma- 
nent command, then you must append a dot to the file name. For example, to load the Editor, type: 



( P ) EDITOR. ( Enter ] 
or 

( P ) EDITOR. (Return) 

Without the period, the system would try to load EDI TOR . CODE, which is not what you want. 

Translating Files from One Type to Another 

Sometimes you may want to translate the contents of a file from one file type to another. For 
instance, you may have a file of type .TEXT, created by the Editor, and wish to read it with the 
BASIC system. BASIC understands the LIF ASCII (.ASC) format, but not the TEXT format. You 
can use the Filer's Translate command in this situation. A typical dialogue would be: 



Translate what file? 
EXAMPLE. TEXT ( Return ) or (BJTERl 
Translate to what? 
EX AMPLE. ASC (Return) or (ENTER) 

For Translate to make sense, the source file must contain data that is textual in nature; attemp- 
ting to translate a .CODE file, for example, would not make sense. 

Translating Text Files to the Printer 

Another situation where translation is required is to move a file from a disc volume to the 
printer. The file may be a .TEXT, .ASC or DATA file . The way such files are stored on the disc 
is not compatible with unblocked devices (such as the printer), so you must use the Translate 
command. Just type in: 



m 

Translate what file? 



WORK . TEXT (Return) or (ENTER) 
Translate to wha t? 
PRINTER: (Return) or (ENTER) 

This example illustrates several points. First, in the Filer environment you must always specify 
the complete file name including the suffix. Second, to send a file to a device like the printer 
which has no directory, there is no point in specifying a file name. Just use the volume name. 
Had you specified a file name after PRINTER: the Filer would have given you an error message. 
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Wildcards 

In the Filer environment you can specify a particular file or set of files by giving a pattern which 
identifies the files you want. These patterns include special characters called wildcards. 

For example, we can use the wildcard = (equal sign) to list a subset of the file using the Filers 
List Directory command. From the Filer subsystem, press: 



CO 

The computer responds with: 
List what directory? 

Respond with: 



FILE= [ Return ) or (ENTER) 

FILE= uses the equal sign wild card to specify all files whose names begin with FILE and end 
with any sequence of characters. Using our example system, this command sequence would 
produce: 



SYSVOL: Directory type= LIF level 1 

created 9-Ausf-82 21.13.37 block size = 256 

changed 9-Au<J-82 21.13.37 Storage order 
...file name.... » blKs * bytes last chnfl 

FILEINTRD.TEXT E4 1G384 28-0ct-82 

FILEINTRO.ASC 73 18G88 2B-0ct-82 

FILES shown=2 allocated=4 unal 1 ocat ed=7G 

BLOCKS (258 bytes) used=201 unused =4499 largest space=4493 



Notice what happened here. The Filer recognized that the response to the prompt, "List what 
directory?", specified not just a volume name but a set of files within that volume. 
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More than one wild card may appear in a single file specification given to the Filer, allowing you 
to easily describe some rather complex operations. For instance, you can copy all the files on 
unit #13 whose names contain the characters INT to the system volume by means of this 
command sequence: 

CO 

Fileoopy w h at f i 1 e ? 

*13: = INT= (Return) or (ENTER) 
Filecopy to what? 
»$ (Return) or (ENTER) 

This example uses the destination wildcard "$", which means "use the same name as the 
source file had". The command locates each file on unit #13 whose name matches the pattern, 
and writes a new copy with the same file name on the system volume. Remember that * is 
shorthand for the name of the system volume. 

You can use "?" as a wild card instead of " = ". Question mark works like equals, except that 
for each file whose name matches the specification, the Filer will ask if you want to perform the 
operation. For example, to have the Filer change each file name on the default volume begin- 
ning with FILE into a file name beginning with WORK, type in: 

Change wha t f i le? 
FILE?(Jeturn) or (ENTER) 
Change to what? 
WDRK= (Return) or (ENTER) 

This would for example turn FILE_ONE.TEXT into WORK_ONE.TEXT. Each time the speci- 
fication is met, the Filer will present what it has found and ask if the process should be 
completed for the entry. Answer with Y for yes or N for no each time you're asked. 
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File Names to Avoid 

The file system won't prevent you from creating file names containing wildcard characters, but 
you'll be sorry if you do. The Filer will think such file names are wildcard specifications instead 
of simple file names. For instance if you created a file called = .TEXT, then used the Filer 
sequence: 



( 


R ) 








R 


e in o i.i e 


what 


f : 


ile? 


= 


♦ TEXT 


( Return ) 


or 


[ENTER] 



the Filer would remove every file whose name ends in .TEXT in the default volume! 

Should you ever accidentally create a file with a wildcard in its name in volume VOLNAM, you 
can get rid of it this way: 



CO 

Remoue what file? 



UOLNAM : ? (Return) or (ENTER) 

This will cause the Filer to offer to remove each file in the directory VOLNAM:. You can then 
remove the problem file, and retain the other files. 

Allowable File Names 

What file names are allowable depends on the type of directory used on the volume in which 
the file resides. In other words, the directory organization makes the file name rules. The exact 
rules for file names are given in the section Programming with files in this chapter. Here is a 
summary of the rules. 

It is wise to choose names consisting of alphabetic letters and digits; if you want a punctuation 
mark within a file name, a hyphen, an underscore, or period is acceptable. Blanks are removed 
from file names. 

In LIF directories and SRM directories, upper and lower case letters are distinct; "CHARLIE" is 
not the same file as "Charlie". In WS1.0 directories lower-case letters in a file name will 
automatically be converted to upper-case. This exception makes it easier to use wildcards to 
move files from one type of directory to another. Only upper case suffixes are allowed in LIF 
directories. Lower case suffixes in LIF directories will cause an error. 

Don't use the following characters: 

Filer wildcard characters. 

Used in specifying volumes. 

Have special meaning with the Shared Resource Manager. 

Used to specify the size of a file when it is created. 

Control characters are automatically removed from file names. 

Blanks are removed from file names. 



"$" 


, "?'' 


\ " = " 


"#" 


4 *. ' ' 


, "#" 


"/", 


"<", ">" 


"[", 


"]" 




con! 


trol c 


haracters 
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File Name Length 

In LIF directories, file names (without suffix) are limited to 9 characters. If the last character in 
the file name is not an A, B, C, S, or T, then 10 characters can be used. If a suffix is present, up 
to 9 characters may precede the dot and suffix. 

In WS1.0 directores, file names may be up to 15 characters including the suffix. 

In SRM directories, file names may be up to 16 characters including the suffix. 

No Room on Volume 

Obviously there is a limited amount of space in a disc volume. When there is no room on a 
volume to create a new file, the system will report an I/O error. 

You may be able to solve this problem by using the Filer's Krunch command. This command 
consolidates all of the volumes free space by moving all of the files on a volume to the front of 
the volume 

Both the LIF and WS1.0 directory organizations are designed for "contiguous file space alloca- 
tion". This means that when space is reserved for a file, the disc sectors set aside have sequen- 
tial numbers. For instance a file requiring 3 sectors might get sectors 26, 27 and 28; or 31, 32 
and 33. Files would not be allocated sectors 13, 56 and 2, because those sectors are not 
logically adjacent. To go back to the analogy with file folders in a drawer, if you had a file too 
big for one folder you might put it in two or three folders; but you'd want store them next to 
each other, not in random places in the drawer. 

When a file is purged, all of its sectors are again available for use by another file. As files are created 
and purged, the disc space usage will develop "holes" of free space between valid files. This is 
called "fragmentation". It's possible for a considerable amount of free space to exist in the volume, 
yet be unusable because it is in pieces too small to use. Since files tend to be small compared to the 
total space on a volume, this problem usually occurs when the volume has relatively little free space 
left. 

To see how fragmented your volume is, use the Filer's Extended Directory List command. This 
command lists both the files and the empty space on the volume. 
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The Shared Resource Management System 

The concepts presented so far have all been applied to local mass storage devices. The same 
concepts extend naturally to deal with shared mass storage. 

The Shared Resource Management System (SRM) allows several workstations (computers) to 
be connected into a network that allows sharing of files and resources. This network is 
controlled by a system controller. Since files can now be shared between several users, a new 
directory structure is needed. Setting up the SRM system is not described in this manual; see 
the SRM documentation for that information. Configuring your workstation to access an SRM 
system is described in the Special Configurations chapter. 

Hierarchical directories 

The Shared Resource Management System uses a hierarchical directory structure to organize 
its files. This directory structure is a multi-way tree data structure. That is, the first, or top 
directory in the structure is called the root directory. Subordinate to the root directory are other 
directories which, in turn, may have further subordinate directories. Each directory may contain 
files or other directories. When a directory contains only files, it is called a leaf directory. All 
files can be called leaf files. The drawing below shows a hierarchical directory structure. 



SYSTEMS 



SYSTEM_P 



WORKSTATIONS 




USERS 



SYSTEM 



EDITOR 

FILER 

COMPILER 




SYSTEM21 SYSTEM45 ROGER BOB FRED 

/ I \ 

WORK WORK WORK 



The directory SYSTEMS is a special directory used by the BOOT ROM, version 3.0 or newer, 
to automatically load operating or language systems. 

The directory USERS has three subordinate directories: ROGER, BOB, and FRED. Each sub- 
ordinate directory has a single file called WORK. Each file and directory is uniquely specified by 
the list of directories from the root to the file. That means several files of the same file name can 
exist without confusion if they are in different locations in the directory structure. 

To save space, the Filer's Duplicate Link command can be used to link a file into a directory 
other than its original location. This allows you to have access to a file, such as the Compiler or 
Editor, without making an extra, unnecessary copy. See the Filer Chapter of this manual for 
more information. 

Once a duplicate link has been set up, if the directory is purged, what happens to the link? Only 
the purged directory loses access to the file. All other directories with links to the file can still find 
it. The disc space allocated to the file is only reclaimed when no directories have links to it. 
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Notation 

Hierarchical directories are a simple concept, but we need some specialized words and notation 
to talk about them. 

The directory at the top of the hierarchy is called the "root" directory. If we want to refer to a 
file or directory which is immediately under the root, for instance WORKSTATIONS in the 
illustration above, we would write 

/WORKSTATIONS 

This is read as "slash WORKSTATIONS" or "stroke WORKSTATIONS". The / indicates the 
root directory. 

To go further down the hierarchy, for instance to SYSTEMS under WORKSTATIONS, write 
/WORKSTATIONS/SYSTEM 

and for another level yet 

/WORKSTATIONS/SYSTEM/COMPILER 

As you can see, to specify a file, the list of directories from either the root directory or the 
current working directory to the target file must be specified. The list is delimited with a /. 

Such a sequence of strokes and filenames is called a directory path, since it indicates the path 
one must follow down the hierarchy to get to a particular file. 

SRM Units and Volumes 

A workstation connected to an SRM normally has units #5: and #45: set up for SRM access. 
The use of two units is in keeping with the idea that there are usually two special volumes (the 
system volume and the default volume) through which most file accesses occur. 

If the workstation is booted from SRM, unit #45: will automatically be configured to be the 
system volume and unit number #5: will be available for use as the default volume. If there is 
local mass storage, the system volume can be any volume you desire. To set these volumes, use 
the What command from the Main Command Prompt. 

Here is how the Filer's Volumes display might look right after booting up a workstation con- 
nected to the SRM and having no local mass storage: 

Mo 1 umes on-line: 

1 CONSOLE: 

2 SYSTERM: 
5 # SRM: 

G PRINTER: 

45 * SYSTEM45: 

Prefix is - SRM: 

You can see that the system starts out with #5: as the default volume and #45: as the system 
volume. 
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Where do the names SRM: and SYSTEM45: come from? They are actually the names of 
particular directories in the SRM's hierarchy. In this example, the name of the SRM volume is 
SRM, and the workstation we are using is at node address 45. Since there is a directory 
SYSTEM45, it is selected as the system volume. All of this selecting is done by the TABLE 
program as it automatically configures the system each time you boot. 

If you need to specify the SRM volume's password, you can do it by using this syntax: 
SRM : / t < passwo rd> 

The SRM volume password is also the SRM root directory's password. That is, they specify the 
same thing. 

Moving Up and Down the Hierarchy 

It would be tedious to type a directory path every time you wanted to access a file. To avoid 
this, you can specify the current working directory using the Filer's Unit Directory command. 
The current working directory can be used as the "root" to specify subordinate files. 



CO 

Set unit to what dir ect ory? 
»5: /USERS/ROGER (Return) or (ENTER) 

Once you have done this, unit #5: is in effect a volume named ROGER: which contains all the 
files under directory ROGER in the hierarchy. It's as if you had inserted a disc called ROGER: in 
a disc drive. If you now command the Filer with: 

m 

List what dir e ctor y ? 
ROGER: (Return) or (ENTER) 

it will list all the files in subdirectory ROGER:. You could also use the sequence: 



CO 

List what directory? 
*5: (Return) or (ENTER) 

since directory ROGER: was installed in #5: by the Filer's Unit Directory command. 

Suppose that under ROGER is another directory named MYSTUFF which contains more files. 
To list the files in MYSTUFF, use the sequence 



CXD 

List what dir e ctor y ? 
ROGER : MYSTUFF (Return) or (ENTER) 

The Filer will realize that MYSTUFF under volume ROGER is itself a directory, and list its 
contents. If MYSTUFF were not a directory, it would simply be listed as a file in directory 
ROGER. 
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You can move the current working directory still farther down the hierarchy in the obvious way. 
For instance to make MYSTUFF the current directory of #5: 



CO 

Set unit to what directory? 
• 5 : MYSTUFF ( Return ) or (ENTER) 

There was no need to specify the entire pathname from the root, because MYSTUFF was 
already accessible as a file within volume ROGER. 

A special notation is provided to move up the hierarchy. Two periods can be used to denote the 
"parent" directory of a file. For instance, after moving down to MYSTUFF, unit #5: could be 
moved back up to the parent directory ROGER by: 



CO 

Set unit to what directory? 
«5: . . (Return) or (ENTER) 

To go up two levels, use the double-period twice, separated by a slash: 



CO 

Set unit to w hat dir ectory? 
#5: . ./, . (Return) or (ENTER) 

This can be executed all the way up to the root directory. Of course, if you want to get all the 
way to the top, it is easier to go there directly, using a stroke as the "name" of the root 
directory. For instance, while #5: is assigned to MYSTUFF you could list all the files in the root 
directory with the command sequence 



m 

List what directory? 
*5s/ ( Return ) or (ENTER) 
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Default Volume vs. Current Working Directory 

The current working directory concept is different from the default volume concept. Specifying 
a current working directory is like installing a disc into a drive unit. Specifying a default volume 
simply tells the file system what volume name to use when none is specified with a file name. 

The two concepts can come together in the Filer's Prefix command. For instance, typing: 

m 

Prefix to what directory? 

«5:/USERS/BIG_USER (Return) or (ENTER) 

has two effects since #5: is an SRM unit. The current working directory of #5: is set to 
/USERS/BIG_USER, and the default volume name is set to BIG_USER. If we now type: 

QD 

Set un it t o w hat directory? 
«5 : , ♦ (Return) or (ENTER) 

the current working directory of #5: becomes USERS (the parent of BIG_USER). However the 
default volume name is still BIG_USER. So the command 



CED 

L i stw hat directory? 
: [Return) or [ENTER] 

will fail with the message that BIG_USER is not on-line! 

The same sort of mistake is commonly made with the system volume. Suppose the current 
working directory of #45: is SYSTEM45, and the COMPILER, EDITOR and other system files 
are under SYSTEMS. If the current working directory of #45: is changed, the Operating 
System won't be able to find the system programs since it thinks of them as 
SYSTEM45:COMPILER and so on. If this happens, you need to get into the Filer and restore 
the current working directory of #45:. How can you do so if the Filer is no longer on-line? You 
will need to execute the Filer by name, specifying a path all the way down from the root to 
wherever it is: 

( Select ) ( ("EXECUTE ) ) 

Execute what file? 

«45:/W0RKSTATI0NS/SYSTEM/FILER. (Return) or (ENTER) 

Note the dot after the Filer's name. You don't want the system to append .CODE in this case. 
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SRM Concurrent File Access 

The SRM system also provides the capability of several users concurrently accessing "shared" files. 
For further information on this capability, see the "Programming with Files" chapter of this manual. 

SRM Access Rights 

You can restrict the use of SRM files with special "access right" password-protection scheme. For 
further information on this capability, see the "Programming with Files" chapter of this manual. 
Also see the Access command description in the "Filer" chapter for more information on assigning 
and removing SRM passwords with the Filer. 
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The Editor 



Chapter 



Introduction 

This chapter introduces the features of the Workstation Pascal Editor. The Editor enables you to 
create, change, store, and retrieve text files, which may be either programs or other textual docu- 
ments. Like other parts of the system, the Editor has visual reminders (prompts) and uses single- 
keystroke commands. 

The Editor is a cursor-based screen editor. The cursor, normally shown on the screen as a blinking 
underline character, shows where subsequent characters will be inserted into the text. You can 
rapidly access any part of the text file by moving the cursor to the desired location. 

The programs and documents created by the Editor are usually stored as text (.TEXT-suffix) files, 
but can also be stored as ASCII (.ASC-suffix) or data (no suffix) files. 

This chapter has four main sections: 

• The first two sections, "Entering the Editor" and "A Sample Editor Session," demonstrate 
how to enter and use the Editor by leading you through writing a short Pascal program. 

• The next section, "A Closer Look," presents more detailed information about the Editor. 

• The last section, "Editor Commands," contains an overview and summary of all the Editor 
commands, as well as a syntactic and semantic description of each command, in alphabetical 
order. 

Once familiar with the Editor, you can use the overview/summary of the Editor commands for quick 
reference. 
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Entering the Editor 

It is assumed that the Pascal System is already "up and running" 



Command: Compiler Editor Filer Initialize Librarian Run execute Version ? 



This prompt tells you that you are at the system's Main Command Level - the level from which 
all the Pascal subsystems (Compiler, Editor, Filer, etc. ) are entered. Entry to any subsystem is 
accomplished by typing the first character of the name of the subsystem you wish to enter. 



Note 

If you have a system workfile (created in a previous Editor session or 
in the Filer subsystem), first go into the Filer and use the Save, New 
and Quit commands to store and release the workfile. Then exit the 
Filer subsystem. 

When the system is delivered to you, the Editor is on the disc labeled "ACCESS:" and is 
named: 

ACCESS:EDITOR 



Now press the [ E ) key. You can use uppercase or lowercase: the computer treats both 
exactly the same while at the Main Command Level. If the Editor code file is on-line, the screen 
clears and displays: 



Loadinsr 'ACCESS : EDITOR 



If you copy the Editor code file to another disc, which has a different volume name, you should 
tell the operating system where to look for the Editor. (See the What command in Chapter 1) 
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Creating a Text File 

When you enter the Editor, the following prompt is displayed. 



Editor [Rev. 3.0 15-Apr-8a] 

Copyright 19B2 Hewl e t t- PacKa rd Company. 
All rishts reserved. 

No worKfile found. 

File? (<ent> for new filet <stop> exits) 



This tells you that you are ente ring th e Editor without a system workfile and requests a file 
name. Respond by pressing the ( Return ) or (ENTER) key to instruct the Editor to create a new text 
file for your use. The file will be named later when leaving the Editor. 

The Editor can also be directly entered from the Compiler subsystem. This is covered in the 
Compiler chapter. 

The Editor Prompt 

The screen clears again and displays the Editor prompt on the top line: 



>Edit: AdJst Cpy Dlete Find Insrt Jmp Rplace Quit XchnS Zap ? 



You are now in the Pascal Editor with a new file. The Editor prompt shows the most common 
commands used in the Editor. This is called a "prompt" because it prompts you to take some 
action, i.e., give the Editor a command. 

The first character of the prompt l ine ( > o r < ) in dica tes the direction of cursor movement (i.e., 
the way the cursor moves when ( TAB ) , (Return) or (ENTER) keys, or the space bar is pressed). 
When the ">" character is displayed, the cursor will move "forward" in the text. Similarly, 
when the "<" ch aracter is displayed, the cursor will mov e "ba ckwards" in text. Pressing 
( > ) , CZZD> or ( i ) wi U set forward direction, while ( < ) , ( , ) , or ( • ) will set 
reverse direction. 

The character indicates the direction that searches take place in the Find and Replace com- 
mands, also the Delete and Page commands. 

The prompt line shows a partial list of commands available in the Editor. To see the rest of the 
commands, type ( ? ) . The screen shows the Editor's alternate prompt: 



> E d i t : MarSin P a J e Set environment Verify ? 



C3.0D 
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This alternate prompt also shows the revision number of the Editor enclosed in brackets. Type 
( ? ) again and the main Editor prompt reappears. 

All of the commands in the Editor are initiated by typing a single key corresponding to the first 
character of the command shown in the Editor prompt. Again it does not matter whether the 
character is uppercase or lowercase — the Editor accepts either one. Now that you are in the 
Editor and understand something about the Editor prompt, let us begin the sample Editor 
session. 

A Sample Editor Session 

Feel free to skim this section if you are familiar with screen oriented editors. You may even 
prefer to try out the Editor commands on your own. If you choose to experiment with the Editor 
commands, do not use any files you cannot afford to lose. 

If you are still reading, step through the following examples on your machine. Doing the 
examples will help you learn faster than just reading about them. 

Creating Text 

The most direct way to generate text is with the Insert command. Initiate the Insert command by 
pressing ( I ) and the screen responds with the following prompt: 



> I n s e r t : Text < h s > t < c 1 r 1 n > C < s e 1 > a c c e p t s > <sh-sel> escapes] 

While in the Insert command, any of the regular character-entry keys (the main keyboard) or 
the numeric pad keys (on the right ) may be used. With a few exceptions, using the key clusters 
on the top of your keyboard or ( CTRL ) key sequences is not advised. (Most of these keys 
generate a question mark (?) while in the Insert command. Others have results which may 
surprise you). Use ( CTRL ) key sequences only if you are working with Stream files. (See Chapter 
1 for details on the use of Stream files). The exceptions are the cursor control keys, 
( BACKSPACE ) , ( CLR LN ) , (ANY CHAR) and ( DUMP ALPHA ] (which sends a copy of the screen image to 
your printer). 



Let's start typing in a Pascal program now. Press (Return) or (ENTER) and then type the text shown 
in the following display. If you make a mist ake, use ( BACK SPACE ) to move the cursor backward 
and then type the correction. You can use ( CLR LN ) to delete the most recently inserted line. 
Prompts in the Editor always show actual key options in the form of a key abbreviation shown 
in (< ) and ( >) symbols. 

The word "binary" is misspelled in the display; leave it that way for now. 

Notice that when you press ( Return ) or (ENTER) after typing the first line, the cursor r eturns to 
column one (the column that the "P" in PROGRAM is in). To type the secon d li ne, us e ( TAB ) to 
indent the comment enclosed in the braces. The next time you press ( Return ) or (ENTER) the cursor 
automatically returns to the indented position created in the previous line. This indenting 
feature proves handy when writing Pascal programs as it adds visual clarity to the code. 
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>Insert: Text <bs>» <clr ln> 



[ < s e 1 > accepts t <sh-sel> escapes] 



PROGRAM Bine rv_search( INPUT , OUTPUT) i 

{This program does a binery search 
on an array of characters to find a 
"key" character input by the user.} 



The display above shows what your screen should look like after the first few lines are type d. To 
move the cursor back to column one for the next line, press and hold [ BACK SPACE - ] . The 
keyboard automatically "repeats" any key that remains pressed. 



> I n 5 e r t : Text <bs>> < c 1 r ln> 



[<sel> accepts i <sh-sel> escapes] 



PROGRAM Bine ry_search( INPUT .OUTPUT) i 

■CThis proSram does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 

VAR done : BOOLEAN! 

Key ! CHAR! 

alpha : ARRAY CI. .26] of CHAR! 

Ioopi topi Midi btm : INTEGER! 



When your screen looks like the display above, press ( Select ) ( ( EXECUTE ) ) to complete the 
insertion. The screen displays the Editor prompt along with the text you inserted. Next we will 
save this program fragment on the disc and then return to create more text. 

Storing Your File and Returning to the Editor 

This section shows how to save a file on a disc and then return to the Editor. It is a good idea to 
do this periodically when writing and editing large text files. Although power outages occur 
infrequently, it can be devastating to lose an entire session of work. Occasional updating of your 
file secures your work against this possibility. 

Press CjO to initiate the Quit command. The screen clears and displays: 



>Ouit : 



Update the worKfile and leave 

Exit without updating 

Return to the editor without updating 

Write to a file name and return 



Before typing anything, find the di sc labe led DOC : and insert it in your disc drive in place of the 
disc labeled ACCESS : . Now press [ W ) and the screen displays: 



>0uit : 

Name of output file Kent) to return) --> 
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The p rompt isrequesting a file specification. Respond by typing DOC:BINSEARCH followed by 
(Return) or (ENTER) . The screen now displays: 



>Oui t ! 

Wri t in s . , 

Your file is 275 bytes Ion 3. 

Exit from or Return to the editor' 



The exact number of bytes may differ with what is indicated in the line above. 



Now press ( R ) . The screen fills with your text and the cursor is positioned where it was when 
you initiated the Quit command. 

Copying Text from Other Files 

The Insert command is the most common way of creating text but other commands are avail- 
able. The Copy command allows you to copy specified text from another file. 

On the DOC: disc is a text file called BINDOC .TEXT which yo u are going to copy into your 
current text file. Position the cursor by pressing [ J ) and then ( E ) (for Jump to End). This 
command sequen ce mo ves the cursor to the end of your text file. (More on the Jump command 
later). Now press ( C ) and your screen displays: 



>Copv: Buffer File <sh-s-ei: 



1 



The Buffer option is demonstrated along with the Delete command later in this section. Now 
press ( F ) (to Copy from a File) and the new prompt appears: 



> C o p v : FileC markeri mar Her] ? 



The system is requesting a file specification. Type D0C:BIND0C and press (Return) or (ENTER) . 
The .TEXT part of the file name does not have to be typed; it is automatically supplied by the 
Editor. The volume name , DOC :, had to be specified because otherwise the Editor would look 
for the file on ACCESS:, the default volume. See Chapter 2 for further information on the 
default volume. 
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The entire file DOC : B I NDOC . TEXT has been copied into your current text file in memory. 
The copy always occurs at the cursor position. This is why you moved the cursor to the end of 
the file before the copy. The screen now appears as follows: 



>Edit: AdJst Cpy Dlete Find Insrt Jmp Rplace Quit XchnS Zap ? 

PROGRAM Binery_search( INPUT (OUTPUT) i 

{This program does a binerv search 
on an array of characters to find a 
"key" character input by the user.} 



MAR 



1 OOP 1 t OP t 



done 

Key 

alpha 

mid t b t m 



BOOLEAN! 

char; 

ARRAY [1, 

integer; 



.26] of CHAR! 



•{initialize} 
=CHR( loop+64) ! 
for a Key ' ) i 



BEGIN -CBinery_search} 
done:=FALSEi btm:=0! top:=2G! 
FOR 1oop: = 1 TO top DO al phaC 1 o op ] : 
WRITELN( 'Type uppercase character 
READ(key)! WRITELN! 
WHILE NOT done DO 

BEGIN {This is the actual binerv search} 

mid:= ROUND((top + btm)/2)i 
IF key = alphaCmid] THEN done:= TRUE 



ELSE IF key < alphaCmidl 

ELSE btm: =mid i 

IF top=btm THEN BEGIN 



THEN top:=mid 



To Copy only part of a file, a beginning and ending marker are specified. These markers must 
have been previously set in the text file being copied. (See the Set command in the "Editor 
Commands" section of this chapter for further information on setting markers). Now that you 
have your screen full of text, let's look at the general pattern of leaving an Editor command and 
some ways to move the cursor. 

Confirming or Aborting Commands 

The ( Select! ( [ EXECUTE ) ) key tells the Editor to accept all of the insertions or chang es you have 
made in the text file. The cursor remains w here it was when you pr e ssed (Select ) . Conversely, 
holding down the ( SHIFT ) key while pressing (Select] (shown as ( SHIFT ) - ( Select ) ) tells the Editor to 
ignore all of the changes made since init iating the command and leaves the cursor where it was 
when the command was initiate d. (The ( ESC ) ke y also p erforms this function on keyboards so 
equipped. ) Both key sequences ( ( Select ) and ( SHIFT ) - (Select) ) return you to the main Editor prompt. 

The changes are stored in the computer's internal read/write memory but are not made permanent 
on a mass storage medium until you exit the Editor and use one of the options that writes the 
information to a file. 
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Not all commands let you abort changes with ( SHIFT ] - [ Select ) and not all require ( Select ) for accept - 
ance. For instance, the Copy from buffer command is accomplished by simply pressing ( C ) 
( B ) . The text is copied and the Editor's prompt appears with no other action on your part. 
The specifics of how each command uses these keys is discussed as each command is pre- 
sented. 



Moving the Cursor 

Now that you h ave s ome t ext on the screen , experiment with positioning the cursor. The arrow 
keys, the ( Return ) and (ENTER) keys, the ( Tab ) key, the space bar, the mouse, and the cursor wheel 
(also called the knob) all move the cursor. The wheel norm ally mo ves the cursor left or right, 
depending on which direction you turn it. If you hold down the [ Shift ) key while turning the wheel, 
the cursor moves up or down while remaining in the same column position. 

An integer in the range 1 to 9999 can be used as a "repeat factor" before all of the cursor 
control keys an d some of the Editor commands. (Repeat factors must be in the range 1 to 4095 
for use with the ( TAB ) key). The result will be the same as if you had pressed the key that many 
times. For instance, typing the number HI and then pressing the space bar causes the cursor to 
move 42 characters in the current direction. 

The Jump Command offers another means of cursor positioning. Press ( J ) and the top of 
your screen displays: 



>JUMPi BeSin End Marker <sh-sel> 

PROGRAM Bine rv.se arch (INPUT. OUTPUT) ! 

■CThis proSram does a binery search 
on an array of characters to find a 
"Key" character input by the user.) 



Typing ( B ) causes the cursor to jump to the beginning of the file, in this case d irectly above 
the (P) in PROGRAM, and the Editor's main prompt reappears. Now press ( J ) then ( E ) 
and the cursor moves to the end of your text file as shown in this partial display: 



IF key = alphaCmid] THEN done:= TRUE 
ELSE IF key < alphaCmid] THEN top:=mid 
ELSE b tm : =mi d 5 
IF top=btm THEN BEGIN 

done:=TRUEi rnid:= -1 

end; 



END! 

IF mid>0 THEN 
WRITELNt 'Key 
ELSE WRITELNf ' 
END. 



(key 



key 



- is 
ikey » 



in position ' »mi d : 2 ) 
- was not found')! 



You can also Jum p to previously set markers (see the Set command in the "Editor Commands" 
section) by typing ( J ) ( M ) followed by a marker name. 
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The beginning and end of a file are simply the first and last characters in the current text file. In 
this case, the position directly above the (P) in PROGRAM and the space following the final word 
END ♦ are the first and last characters, respectively. The Editor adjusts these internal pointers 
automatically as the text file is changed. 

The Page command lets you move through a fil e one scre en (23 lines) at a time. It is roughly 
equivalent to using a repeat factor of 23 with ( t ) or ( I ) d epend i ng on the direction 
shown in the prompt. If the cursor is not at the end of the file, pr ess [ J ) ( E ) . Now type < 
to change from the forward to the backward direction and press ( P ) (for Page). The top half 
of your screen now looks like: 



<Edit: Adjst Cpy Dlete Find Insrt Jmp Rplace Quit XchnS Zap ? 

PROGRAM Bine rv.searchf INPUT .OUTPUT) ! 

■CThis program does a binery search 
on an array of characters to find a 
"Key" character input by the user.) 

JJ'AR done : BOOLEAN! 

Key : CHAR i 

alpha : ARRAY CI. .26] of CHAR) 

loop. top. mid. btm : INTEGER! 



BEGIN {Bine rv_sea rch > 
done:=FALBEi btm:=0i top:=2Gi 



{initialize} 



Notice that the cursor is positioned at the V AR declaration in the program which is 23 lines from 
the end of the file. Since the cursor movement direction is still backward, type > to change it to 
forward. The Page command is especially handy when moving through a large file. 

Deleting Text 

Now p osition the cursor under the first bracket on the second line of the program and press 
( D ] . This initiates the Delete command. Moving the cursor removes text from the file. To 
restore the text, use any curs or control k ey which moves the cursor back over the area where 
text has been removed. The ( BACK SPACE~) key and the cursor wheel work well for this. 

Upon pressing ( D ) , the screen displays: 



>Delete : 



> <MovinS commands> [<sel> deletes. <sh-sel> aborts] 



PROGRAM Binery_search( INPUT .OUTPUT) i 

{This prosTam does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 



VAR 



done 

Key 

alpha 

loop. top. mid. btm 



BOOLEAN! 

CHAR! 

ARRAY [1..2G] of CHAR! 

INTEGER! 
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First m ake sure the direction is forward (>) as shown above and then type 4 followed by ( Return ) or 
(ENTER) . This uses a repeat factor and moves the cursor 4 lin es, de le ting text as it goes. (The 
deleted text is temporarily stored in the copy buffer). Now press ( Select ) ( ( EXECUTE ] ) and the screen 
displays: 



>Edit: AdJst Cpy Dlete Find Insrt Juip Rplace Quit XchnS 

PROGRAM Bine ry_search< INPUT .OUTPUT) i 
MAR done : BOOLEAN! 

key : CHAR! 
alpha : ARRAY C1..2B] of CHAR! 
loop. top. mid. btm : INTEGER! 



Before typing any other keys or moving the cursor, press ( C ) then ( B ) . This takes the 
information stored in the copy buffer and copies it into the text file beginning at the current 
position of the cursor. Since the Delete command just filled the buffer with the text that was 
removed, the Copy from Buffer command simply returns the screen to its state before the 
Delete command was entered. 



The top of the screen should now display: 



>Edit: AdJst Cpy Dlete Find Insrt Jmp Rplace Quit XchnS Zap 

PROGRAM Binery_search< INPUT .OUTPUT) ! 

■CThis pro 3 ram does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 



MAR 



1 OOP . top t 



done 

key 

alpha 

mid. btm 



BOOLEAN! 
CHAR! 
ARRAY [1, 
INTEGER! 



,261 of CHAR! 



Recovering Deleted Text 

As the ex ample s hows, even if you complete the Delete command using ( Select ) ( ( EXECUTE ) ) 
instead of ( SHIFT ) - (Select ) , you can still change your mind and recover that text using the Copy (from 
buffer) command. Take care not to wait too long or depend on this too heavily as there are other 
commands which alter the contents of the buffer. None of the cursor movements alter the buffer in 
any way. 

Moving and Duplicating Text 

The sequence of the Delete and Copy (from buffer) commands provide a convenient way of 
moving text to different parts of the file. For instance, in the operation just completed above, 
any of the cursor control keys could have been used to reposition the cursor after the deletion 
occurred and before the Copy from the buffer was executed. 

The buffer is "filled" with the text affected by the Delete command and by the Insert and Zap 
commands. Doing a Copy from buffer sequence does not change the contents of the buffer. 
This feature lets you copy the same text in numerous places. 
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Whethe r the Del ete command was completed with the ( Shift ) ( Select ) ( ( EXECUTE ) ) or ( Select ) 
( ( SHIFT ) - ( EXECUTE ) ) sequence makes no difference to the copy buffer. What this means in 
practical terms is that the Delete command allows you to fill the buffer without affecting your 
original text. 

So if you want to duplicate the text instead of moving it to a different location, use the sequence: 



1. Press [ D ) to initiate the Delete command. 

2. Cause some cursor movement. This deletes text and stores it in the copy buffer. 

3. Press ( SHIFT ) - [ Select ] to recover the text that was just deleted. 

4. Reposition the cursor to where you want to duplicate the text. 

5. Press ( C ) [ B ) to execute the actual copy at the new cursor position. 

Changing and Altering Text 

Mistakes or necessary changes in a program or text file are not always obvious when creating 
text. The Editor features commands which allow you to go back and make changes when 
needed. These are the Replace and eXchange commands and the Delete/Insert sequence. 
These will be demonstrated by making corrections to the sample program text. 



Press ( J ~) ( B ) to move the cursor to the beginning of the file and then type 5 and press 
[ R ) to initiate the Replace command. The prompt at the top of the screen appears: 



f 



>Rbp1C5]: L "J <tars><sub>=> 



Press ( L ~) and ( V ) to tell the Editor that you are going to give it a Literal string and that 
you want to operate in the Verify mode. A Literal string may occur as a word or as part of a 
word. The alternative is a Token string which must occur as a word. The Verify mode makes the 
changes one at a time after asking you if you want this occurrence replaced. Now type: 

/ i ri e r v / / i n a r v / 

The slashes are used to delimit the target and substitution strings. Any non-alphanumeric or 
non-control characters can be used as delimiters. This is necessary when the slash is part of the 
search string or replacement string. Notice also that "inery" is specified instead of "binery". 
This is because two occurrences of the word are "Binery". The two words are unequal. 

After you type the final delimiter, the screen clears and displays: 



>Rp1C51: <sh-sel> aborts*R replaces*' ' doesn't 

PROGRAM B ine research! I NPUT*OUTPUT> i 

■CThis prosram does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 
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The cursor is positioned behind the first occurrence of the string inerv. Now press ( R 
watch what happens: 



J and 



>Rp1C4] : 

PROGRAM 



YAR 



< 5 h - s e 1 > aborts >R repUcESi 



doesn't 



Binary_search< INPUT , OUT PUT) ! 
{This proSram does a biner y_s e a r c h 
on an array of characters to find a 
"Key" character input by the user.} 



1 o OP 1 t OP I 



done 

key 

alpha 

mi d i btm 



boolean; 
char; 

ARRAY [1, 

integer; 



.26] of CHAR! 



{initialize} 
:=CHR( 1oop+G4> ! 
for a key') ! 



BEGIN {Bine ry_sea rch } 
done:=FALSE! btm:=0> top:=26i 
FOR 1oop: = 1 TO top DO a 1 phat 1 o op] i 
WRITELN ( 'Type uppercase character 
READ(key)! WRITELN! 
WHILE NOT done DO 

BEGIN {This is the actual binery search} 

mi d : = ROUNDMtop + btm)/2)i 
IF key = alphaCmid] THEN (joner 



ELSE IF key < alphaCmid] 

ELSE btm:=midi 

IF top=btm THEN BEGIN 



TRUE 
THEN top:=mid 
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The first string inerv has been replaced with i ri a r y , the cursor is now positioned behind the 
second occurrence of the target string and the prompt shows that you can make four more 
replacements. Press the space bar (represented by ' 'in the prompt) to leave the string 
unchanged and the screen now displays: 



>RplC3]: <sh-sel> abortsiR replaces) 



doesn't 



PROGRAM Binary_search< INPUT .OUTPUT) i 

{This program does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 



MAR 



loop, t P i 



done 

Key 

alpha 

mid. b tm 



BOOLEAN! 
CHARi 
ARRAY CI, 
INTEGER! 



.283 of CHARi 



BEGIN {Bine ry^search} 
done:=FALSEi btm:=Oi top:=2B! {initialize} 
F : OR 1oop:=1 TO top DO alphaC 1 oop] : =CHR( loop+G4) ! 
WRITELN( 'Type uppercase character for a Key')! 
READ(Key)! WRITELN! 
WHILE NOT done DO 
BEGIN {This is the actual binery search} 
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The cursor is now behind the occurrence of Bine rv following the BEGIN statement. Press 
( R ) to replace this one and then press it again to replace the last occurrence of b i n e r y . 
The screen now displays: 



>ERR0R: Pattern not found. <space> continues. 

PROGRAM Bi r, a rv.sea re h < INPUT .OUTPUT) i 

{This pros ram does a binery search 
on an array of characters to find a 
"Key" character input by the user.} 



UAR 



1 OOP 1 top l 



done 

Key 

alpha 

mid t b tm 



BOOLEAN! 

char; 

ARRAY [1, 

integer; 



.26] of char; 



{initialize} 

:=CHR(1oop+G4) 

for a Key')! 



BEGIN {Binary-search} 

done:=FALSE! btm:=0i top:=2Gi 

FOR 1oop: = 1 TO top DO a 1 phat 1 oop] : 

WRITELN( 'Type uppercase character 

READ(Key)! WRITELN! 

WHILE NOT done DO 

BEGIN {This is the actual b ine ry_sea rch } 

mid: = ROUNDUtop + btm)/2)i 
IF Key = alphaCmid] THEN done:= TRUE 
ELSE IF Key < alphatmid] THEN top:=mid 
ELSE btm:=midi 
IF top=btm THEN BEGIN 



The prompt at the top of the screen tells you that the Editor could not find any more occurences 
of the specified string in the file. The cursor is positioned at the final occurrence of the string but 
it has not yet been changed. Press the space bar and the Editor prompt reappears, the final 
occurrence of the string gets replaced and the cursor remains at the same place on the screen. 

To correct the spelling of b i n ery (which was intentionally skipped), use the eXchange com- 
mand. Move the cursor to the e in b i n ery in the second line of your program. Now press 
( X ) and the screen shows: 



> X c h n J e : Text <bs> <sh-sel> aborts <sel> accepts 

PROGRAM Binary_search( INPUT .OUTPUT) ! 

{This proiram does a bine_ry search 
on an array of characters to find a 
"Key" character input by the user.} 



Type the letter a and then press ( Select ) ( ( EXECUTE ) ). Pressing ( Select ) confirms changes made in 
eXchange and returns the Editor prompt. That's all there is to the eXchange command. 
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You should always position the cursor before initiating eXchange because this command can- 
not cross line boundaries; you can only make eXchanges on the line where the cursor is 
located. 

The eXchange command is handy but the combination of the Insert and Delete commands is 
often a more effective way to change text. For example, to clarify the program by a dding 
comm ents , position the cursor at the comment following the second BEGIN, press ( D ) , and 
press ( TAiQ once. The screen displays: 



> D e 1 e t e : < > < M o v i n S cornmarids> [ < 5 e 1 > deletes i <sh-sel> aborts] 



PROGRAM Binary_search< INPUT .OUTPUT) i 

{This program does a binary search 
on an array of characters to find a 
"key" character input by the user.} 



MAR 



done 

Key 

alpha 

loop» topi midt btm 



boolean; 
char; 

ARRAY CI, 
INTEGER! 



.26] of CHAR! 



BEGIN {Binary-search} 
done:=FALSEi btm:=0i top:=26i 
FOR 1oop:=1 TO top DO alphaCloop] 
WRITELN( 'Ty pe uppercase character 
READ(key)! WRITELNi 
WHILE NOT done DO 

BEGIN { t_he actual 

mid:= ROUNDMtop + btm)/2)i 
IF key = alphaCmid] THEN done:= TRUE 



{initialize} 
=CHR( loop+64) 
for a key ' ) i 



binary search} 



ELSE IF key < alphaCmid] THEN top:=mid 

ELSE btm:=midi 

IF top=btm THEN BEGIN 



Using a co mbina ti on of [TAB ) and the space bar, delete everything between the two brackets 
and press ( Select ) ( ( EXECUTE ) ). Part of the screen looks like: 



WHILE NOT done DO 

BEGIN {.!_ 

mid:= ROUNDMtOP + btm) /Z) i 
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Press ( I ) to initiate the Insert command and notice how a space is opened between the 
brackets. Insertions always occur directly in front o f the c u rsor's pos ition when Insert is initiated. 
Now type in the text shown below and then press ( Select ) ( [ EXECUTE ) ) to complete the insertion. 



WHILE NOT done DO 

BEGIN {This routine compares key to 

middle. A new top or bottom is chosen 
and a new middle computed. The loop 
continues until either Key = middle or 
the array is exhausted.} 
mid:= ROUND((top + btm)/2)i 



Finding Patterns of Text 

If you want to find a particular text pattern, you can use the Editor's Find command. This 
command is similar to the Replace command in that it begins looking for the pattern that you 
specify, beginning at the current cursor location; it also interprets the pattern you specify as a 
Token or a Literal, according to the current Token environment parameter setting. 



Jump to the beginning of the fi le by p ressing ( J ) and then ( B ) . Find the first occurrence of 
the word "loop" by pressing ( F ) and then typing these characters: /loop/. The /'s act as 
delimiters for the pattern that you want to find. These delimiters don't have to be the slash (/) 
character; the Find command uses the first character that you specify as the delimiter (except T 
while in Literal mode and L while in Token mode), so you will need to follow the pattern with the 
same delimiter. For example, you could have specified: "loop". 

When the pattern is found, the cursor is placed at the beginning of the pattern. You can use 
commands to change th e text (such as eX chang e), or you can search for the next occurrence of 
the pattern by pressing ( F ) and then [ S ) (for Find Same). 

If the pattern is not found, then you are prompted with the message: 
> E R R R : Pattern not found. < s p a c e > continues. Press space to answer the 
prompt, which puts you back into normal Edit mode. 

Formatting Text 

The Pascal Editor allows you to format text with the Adjust and Margin commands. Text is also 
formatted by inserting or deleting blanks where needed. 

The Editor's Adjust command provides a means of shifting the starting column of a line of text 
left or right in the file. This command helps make your Pascal programs and other text more 
readable. To increase the clarity of our sample program, mov e the cursor to the word mid 
following the second BEGIN statement in the program. Press ( A ) and the Adjust prompt 
appears: 



> Adjust: LJust RJust Center <arrow K e y s > [ < s e 1 > to leave] 
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Experiment with the Adjust command by pressing [ L ) , ( R ) , or ( C ) . These options move 
text to the left, right, or center. The values used to shift the text are the Left and Right m argins of 
the environment (discussed below). Any of the cursor arrow keys as well as ( BACK SPACE - ] and the 
cursor wheel can be used to Adjust text. Now return the line to its original position and press 
(Select} . Repeat factors are available for use with the Adjust command so that many lines of text can be 
shifted at one time. 



Note 

Think twice bef or e using Adjust with large repeat factors. This is because 
(SHIFT) - (Select) ( ( SHIFT ) - ( EXECUTE ) ), which usually aborts all changes 
made by a command, is not available for exiting the Adjust command. 
Therefore, to recover the original format of your text, you would have 
to Adjust it again. 



Now that the line is in its original place, press ( A ) (to initiat e Adju st), type 3 ( -> ) (to indent 
the text three spaces to the right), and then type G and press ( 1 ) . Watch what happens: the 
cursor moves down six lines and shifts each line three spaces to the right. Thus, the Adjust 
command is useful for indenting entire blocks of text in a Pascal program. 



The screen now looks like: 



t!evs> [<sel > 
{initialize} 
=CHR( loop+Ba) i 
for a key ' ) i 



>AdJust: LJust Rjust Center <arrow 
done : =FALSE ! btm:=Oi top:=26i 
FOR 1oop:=1 TD top DO alphatloop] 
WRITELN ( 'Type uppercase character 
READ(key)! WRITELN! 
WHILE NOT done DO 
BEGIN {This routine compares key to 

middle. A new top or bottom is chosen 
and a new middle computed. The loop 
continues until either key = middle or 
the array is exhausted.} 
mid:= ROUNDMtop + btm)/2)i 
IF Key = alphaCmid] THEN done 
ELSE IF key < alphaCmid] THEN 
ELSE btm:=midi 
IF top=btm THEN BEGIN 

done:=TRUEi 
END! 



to leave] 



:= TRUE 
t o p : =m i d 



mi d : = - 1 



END? 
IF mi 
WRIT 
ELSE 
END. 



d>0 THEN 

ELN( 'Key - ' .key 

WRITELNf 'key - 



'- is in position '»mid:2) 
tkeyi' - was not found')! 



Press (Select! ( ( EXECUTE ) ) to terminate the Adjust command. If you wish to make adjustments in 
other parts of your text file, exit the Adjust command using (Select ) before moving the cursor from 
one area to another. Otherwise you may make unwanted adjustments to your text. 
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The Margin command lets you margin and fill your text according to a pre define d "environ- 
ment". Margin operates on the paragraph where the cursor is located when [ M ) is pressed. 
A paragraph is any text delimited by any combination of blank lines, lines whose first non-blank 
character is the "command character" (see the Set environment command in the section 
"Editor Commands"), or the beginning or end of a file. The Margin command is executed 
completely by pressing ( M ) ; no parameters or options are available. 

Entering the Editor without a workfile or a named file (as you did earlier in this session) 
automatically sets (or defaults) the environment to the "program" environment. This environ- 
ment is optimized for writing programs. When the Editor is entered with either a file name or a 
workfile, the environment associated with that file is the current environment. 

You can alter the environment at any time using the Set (Environment) command. Once you 
have altered or redefined the environment and saved a text file on a mass storage medium, that 
environment is stored along with the text file and is used whenever the Editor is entered with 
that file. 

Since you entered the Editor without a file, your current environment is the Editor's "program" 
environment (the default supplied by the system). The Filling option of this environment is set 
to false (which disables the Margin command) so, if you press ( M ) , the screen displays: 



>ERR0R: WronS env i ronmen t <space> continues. 



If Filling had been set True (with Auto-indent False), the Margin command would fill and Margin 
your program like this: 



PROGRAM Binary_search ( INPUT .OUTPUT) i {This program does a binary 
search on an array of characters to find a "key" character input by 
the user.} 'JAR done : BOOLEAN! key : CHAR i alpha : ARRAY [1..2B] of 
CHAR! loop, top) mid. btm : INTEGER! BEGIN {B i na ry_s ea rch > 
done:=FALSE! btm:=0! top:=26! {initialize} FOR 1oop:=1 TO top DO 
al phat l oop] : =CHR( loop+64 ) ! WRI TELN ( ' Ty pe uppercase character for a 
key')! READ(key)! WRITELN! WHILE NOT done DO BEGIN {This routine 
compares key to middle. A new top or bottom is chosen and a new 
middle computed. The loop continues until either key = middle or 
the array is exhausted.} mid:= ROUND((tOP + btm)/2)i IF key = 
alphaCmid] THEN done:= TRUE ELSE IF key < alphaCmid] THEN top:=mid 
ELSE btm:=midi IF top=btm THEN BEGIN done:=TRUEi mid:= -1! END! 
END! IF mid > THEN WRITELN < ' Key -'.key.'- is in position '.mid:2> 
ELSE WRITELN('key - '.key.' - was not found')! END. 



The previous display gives you some idea of how important it is to know what your environ- 
ment settings are before using the Margin command. The only recovery from this operation is to 
use a combination of the Adjust and Insert commands to rebuild the text. If you have a copy of 
the original file available, you can exit the Editor without updating the file and reenter it with the 
old copy. 
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Note 

The Insert command has effects similar to those of the Margin com- 
mand when the Filling option of the environment is set to True and 
Auto-indent is False. Any ti m e you do an Insert and confirm the 
operation by pressing ( Select ) ( ( EXECUTE ) ), both the inserted text and 
all the text that follows the insertion in that same paragraph are 
automatically margined. 

The Margin takes place according to the Left and Right margin settings of the e nvironment. If 
you begin an in sertion and are not sure of the environment settings, press ( SHIR ) - fSelect ) 
( ( SHIFT ) - ( EXECUTE ) ) to exit the Insert com mand. This way, even if Filling is true, your text will not 
be margined. Then press ( S ) ( E ) to look at the environment settings. 

When writing programs, your use of the environment and the Margin command will probably 
be more limited than when writing other kinds of text. To see how the program environment is 
configured, press ( S ) ( E ) (for Set Environment). The screen displays the default environ- 
ment: 



>E:nu i ronmen t : {options} 
Auto indent T rue 
F i 1 1 i n s 
Left ma ri in 
Risht marsin 
Para ma r Sin 
Command ch 
Token def 
I Sno re case 
Zap ma rKe rs 
275 bytes used 



<sel> or <sp> leaves 



False 


78 
5 

T rue 
False 



348909 available, 



Patterns: 
< t a r 3 e t > = 

Ma rKe rs : 
TDP 



'inery' i < s u b s t > = 



FIX 



' ina ry ' 



File BINSEARCH.TEXT 
Date Created: 10-11- 



Last Used: 10-11-82 



Press the space bar to exit the environment display and the Editor prompt reappears along with 
your text. The cursor is at the position it was when the Set command was entered. 
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Exiting the Editor and Saving the File 

Now that you have finished writing and editing the program, exit the Editor by pressing ( Q ) 
(for Quit). Make sure that the disc named DOC : is in the same disc drive you have been using. 
The screen displays: 



>Quit : 



Update the worKfil-e and leave 

Exit without updating 

Return to the editor without updating 

Write to a file name and return 

Save as file new file BINSEARCH. TEXT 

Overwrite as file BINSEARCH . TEXT 



Respond by pressing ( S ) for Save. If you are on an SRM system, you would use the 
Overwrite option. The Overwrite option allows all duplicate links and passwords to a text file to 
remain accurate after a file has been modified. More information on these options is given in the 
command reference under the Quit command. 



>0uit : 
W ri t in 3. . 
Your file 
Exit f rom 



is 1009 to 
or Return 



t e s Ions. 

to the editor? 



Your program text has been written to your disc and is accessible under the name 
BINSEARCH. TEXT on the volume DOC:. 

If you are creating a file for use with another language system, such as BASIC or HPL, the file 
should be stored as an ASCII type file on a disc with a LIF directory. To accomplish that, use the 
Write option and name the file: 

DOC:BINSEARCH.ASC 

On a LIF directory, the Pascal system codes all the file names that end in a standard suffix. The 
coding scheme removes the period, appends the first character of the suffix to the file name, 
and pads the file name to ten characters with "_" (underscore characters). This allows you to 
specify file names up to 15 characters. They are encoded to the maximum ten characters for the 
LIF directory. The file system encodes the above file name to: 

BINSEARCHA 



In this case, the first character of the suffix is the tenth character so no "_" characters were 
added. This coding mechanism is invisible as long as you are using the Pascal system. When 
you catalogue your disc with other language systems, the coded version of the file name is 
observed. 
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Making a Backup Copy 

The most direct way to make a backup copy of your file is to press ( R ) (to return to the 
Editor) and then press [ Q ) (to initiate the Quit command). Each time you Quit the editor, 
you can make another copy of the file currently in the Editor. 

Press GO for the Write option, type in a name for your backup copy such asDOC:BINBKP and 
press (Return) or (ENTER) . If you have another disc handy, repl ace the DO C: vo lume with it, specify 
the name of the new volume along with a file n ame an d p ress (Return) or (ENTER) . Remember the ten 
character limit for file names. After pressing (Return) or (ENTER) , the screen displays: 



>Qui t : 

W ri t in 3 ♦ . 

Your file is 1008 bytes Ions. 

Exit from or Return to the editor? 



There are now two identical files on your disc(s) of the binary search program. Now press 
( E ) (for the Exit option) and you will be returned to the Main Command Prompt: 



r 



Command: Compiler Editor Filer Initialize Librarian Run execute Version ? 



All the Editor commands covered here are explained in further detail in the "Editor Com- 
mands" section. Less commonly used commands not presented in this sample session can also 
be found there. 
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A Closer Look 

This section contains details about how the Editor works and includes information on the 
cursor, the screen, memory and file sizes and how the Editor allocates space for text files on a 
storage medium. The section also presents information on using workfiles in the Editor, on 
Stream files and on I/O errors that may occur when entering and exiting the Editor. 

The Cursor 

The cursor (the flashing underline symbol on the screen) is a reference point for all of the 
Editor's commands. The action associated with most commands occurs at the cursor position. 
Commands that perform actions on lines or paragraphs act upon the line or paragraph where 
the cursor is currently located. 

You h ave complete control over the cursor through the arrow keys, the ( Tab ) and (Return) or 
[ENTER] keys, the space bar, the mouse, and the cursor wheel (also called the knob). The screen 
cursor's position determines where the Editor will act upon the text, thus reflecting the internal 
cursor's position (in the computer's memory). 

The Anchor 

You can also use the Zap command to delete text. With this command, all text between the current 
cursor position and the "anchor" is deleted. The anchor is set at the position of the latest Adjust, 
Find, Insert, or Replace command. (You can also find the position of the anchor by pressing = .) 

If more that a line of text is to be deleted, you will b e warned as follows: 
>WARNING! Zap more than BO chars? (•// n ) Press QD to confirm the Zap oper- 
ation; press ( N ) (or space bar, etc.) to abort the Zap. 

The Screen as a Window into a File 

Text files are often too large to be shown all at once on the computer's screen (CRT), so the 
Editor uses the screen as a "window" which shows a portion of a file. Depending on which 
machine you have, your CRT can display lines of text that are either 49 or 79 characters long 
while in the Editor. If a line's length is greater than your display area, the Editor puts an 
exclamation point (!) in the last column to inform you that the entire line is not shown. 

The screen is capable of displaying 25 lines of characters at a time. The Editor displays only 23 lines 
of text from a file since the top line is reserved for the system's prompt and the bottom line is 
reserved for the "type ahead" line. The type ahead line displays any characters input from the 
keyboard which have not yet been processed by the system. One other item is displayed in the 
lower right corner of the screen. This is a system status display or "runlight." 

The screen generally displays the cursor and the text surrounding it. (The Set environment 
command is an exception to this). This means that you can move the window up and down 
through your text file by moving the cursor. Whether the text is on or off the screen, it resides in 
the computer's read/write memory and is easily accessed using either the cursor control keys or 
the various editing commands which reposition the window. When an Editor command oper- 
ates on a portion of text it displays as much of that text as possible on the screen. 



The Editor 69 



Memory and File Sizes 

When the Editor is entered, the current text file is stored in the computer's read/write memory. 
All changes that occur to a text file (including text creation) take place in this memory and only 
become permanent when the Editor is exited and the contents of the text file are written from 
memory to a mass storage medium such as a flexible disc. 

The maximum size of the text files that can be accessed or created by the Editor depend on the 
memory configuration of your system. This size can easily be determined using the Set (environ- 
ment) command. The two environment headings, "bytes used" and "available", should be 
added together. The sum equals the maximum size (in bytes) of the text files which can be 
handled by the Editor. 

If your text file approaches the maximum size while you are doing an insertion, the Editor displays 
the following message: 

>ERROR: Finish the insertion (space) continues. 

This tells you that you are nearing the Editor's memory limits. If, after finishing the insertion, you 
attempt to initiate the Insert command again, the Editor informs you: 

>ERROR: No room to insert. <space> continues. 

Here is procedure to help you work around the Editor memory limits (whatever they may be on 
your machine): 

1. Set a marker toward the end of your original file (to be used later). 

2. Quit the Editor, Save the original file, and Exit the Editor completely (in order to reenter 
with a new file). 

3. Reenter the Editor and press ( Return ) or (ENTER) (to create a new file). 

4. Using the Copy from file command, s pecify you r origi nal file and your marker as 
follows: FILENAMECMARKf] and press [Return] or (ENTER) . The name of your file and 
marker will be different; this just shows you the general form. Notice that a second marker 
was not specified so that the copy takes place from the marker's location to the end of the 
original file. 

5. Now, press [ J ) then ( E ) (to Jump to the end of your new file). 

6. Press ( I ) (to initiate the Insert command). 

Now you can continue inserting your text in your new file without too much loss of continuity. 
You may want to go back to your original file and delete the text that was copied into your new file 
so that it will not exist in both files. 
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Structure of Text Files 

The Editor can read and write three types of files. The predominant file type is TEXT. The 
others are DATA and ASCII. TEXT files contain ASCII characters and are structured in a 
particular way. 

In every text file, the first two blocks (or 1024 bytes) are reserved for information about the 
environment settings, the locations of markers in the file and other information the Editor needs 
to work with that file. Since the Editor allocates mass storage in two block increments, text files 
always contain an even number of blocks. Also, because the Editor reserves the first two blocks 
for file information, a file with only a single character will take up 4 blocks of storage space on a 
mass medium. 

It is possible to create a text file that does not have .TEXT appended to the end of the file 
name. If, when exiting the Editor and specifying a file name using the W r i t e as . . ♦ option, 
you place a period (.) at the end of the file name, the Editor will not append . TEXT to the file 
name. The file will appear to be a data file on the directory for the mass storage medium. (See 
the chapter on the Filer for more details on file types and the directory). 

If you want to access this file with the Editor, you must specify the file name followed by a 
period when entering the Editor. If you do not use the trailing period, the Editor appends 
.TEXT to the name you type in and looks for a file with that name on the mass storage 
medium. 

For example, suppose when exiting the Editor you answer the prompt for a file name with 
DUX . . Notice the period following the name. The Editor saves the file with the name DUX (it 
strips off the period) and does not append the .TEXT suffix. If you enter the Editor and want 
that file, you must specify DUX . . If you instead specify DUX (i.e., leave out the period), the 
Editor appends . TEXT to the name you typed and looks for a file with the name DUX . TEXT. It 
may even find a file with that name, but it will be a different file than the one saved by specifying 
DUX. . 

ASCII files are structured differently. ASCII files on LIF discs are compatible with the BASIC 
and HPL language systems that run on your computer. ASCII files are created by writing to a 
file whose name ends in the suffix: 

.ASC 
When writing ASCII files, the Editor's environment information is lost. 

Using Workfiles in the Editor 

A workfile in the Editor is used as a "scratchpad" version of a text file. The workfile is useful 
because it is the default file in the Editor (as well as in many of the Pascal subsystems). Chapter 
2 contains information about using workfiles in all the subsystems; only Editor-related workfiles 
are covered here. 
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There are two ways to enter the Editor: from the Main Command Level or from the Compiler 
subsystem (after the Compiler finds an error in the text file it is compiling). When entering from 
the Compiler, the text file being used is automatically read in. When entering the Editor from 
the main level, the system automatically looks for a workfile and, if it finds one, reads the 
contents of the file into the computer's memory. If the Editor does not find a workfile, it prompts 
you for a file name. 

Exiting the Editor (using the Quit command) gives you the option of Updating the workfile. If 
the Editor was entered with a workfile (or if the Update option was used earlier in the same 
editing session), the Editor writes the contents of the text file in memory to the file called 
*WORK . TEXT on the system volume. When you are through with all your editing, it is a good 
idea to enter the Filer subsystem and Save the workfile. 

Stream Files and the (any char) Key 

Stream files (covered in Chapter 1) can be created by the Editor to simulate a "batch" mode in 
which the computer executes the commands in the Stream file as if they were coming from the 
keyboard. The ( ANY CHAR ) key is useful in this regard. It can be used to generate charact ers which 
may not otherwise be attainable by regular keystrokes. For further information on the (ANY CHAR) 
key and Stream files, see Chapter 1. 

I/O Errors (Entering and Exiting the Editor) 

There are two general types of errors that can occur when entering the Editor. The first type of 
error is generated by the system when it cannot find the volume or file which you specified. The 
solution to this is to make sure that the proper volume is on-line. This type of error also occurs 
when a workfile exists but the Editor cannot find it because the medium containing that file is no 
longer on-line. When the Editor encounters this situation, it informs you that the workfile has 
been "lost" and then prompts you for a filename. 

The second type of error possible while entering the Editor is a memory overflow condition. 
This happens only if the text file being read was created on a machine with more memory than 
the machine currently being used. Note that this condition is met if you use the Permanent 
command (at the Main Command Level — see Chapter 1) to load something into memory that 
was not there when you created the text file. Your machine now has less available memory so 
the space for text files is smaller. 

When a memory overflow occurs while reading in the file, the Editor lets you continue the entry 
process even though the entire file has not been read into memory. However, upon exiting the 
Editor, the Save option is no longer available. This safeguard keeps you from accidentally 
overwriting; your original file. 

When exiting the Editor, a number of different errors are possible. If the Editor detects an error 
while writing the contents of the text in the computer's memory to a mass storage medium, it 
will display a self-explanatory error message. 
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Editor Commands 

This section contains a brief overview and summary of all the Editor commands and a complete 
alphabetized description of the syntax and semantics of all the Pascal Editor commands and 
options. 



Editor Command Summary 



Text Modifying Commands 

Copy — Insert text from the copy buffer or an 
external file in front of the current cursor location. 

Delete - Remove text from the current cursor 



l ocation to the location of the cursor when (Select ) 
( ( EXECUTE ) ) is pressed. 

Insert - Inserts text in front of the current cursor 
location. 

Replace - Replace the specified target string 
with the specified substitute string. 

eXchange — Replace the text at the cursor with 
text typed from the keyboard, on a 
character-by-character basis. 

Zap - Delete all text between the anchor and 
the current cursor location. (The anchor is set at 
the location of the latest Adjust, Find, Insert, or 
Replace command. ) 

Text Formatting Commands 

Adjust - Adjust the column in which a line (or 
lines) start. 

Margin - Format the paragraph the cursor is 
located to the margins in the cunent environment. 

Miscellaneous Commands 

Quit - Leave the Editor in an orderly manner. 
Provides various ways for saving the text currently 
in memory. 



( STOP ) ( ( SHIFT ) - (CLR I/O) ) - terminates the Editor 
subsystem, but the text is lost. 

Set - Modify the environment or set markers in 
the text. 

Verify - Update the displayed text to reflect the 
text stored in memory. 



Curso r Keys 

( TAB ) - Move cursor to next tab position (fixed 
tabs) in the current direction. 

( Return ) or (ENTER) - Move cursor in current 
direction to the leftmost character in the next 
line. 

Space Bar - Move cursor one character in the 
current direction. 

Arrow Keys - Move cursor in the direction 
specified by the key. 

Cursor Wheel - Moves the cursor like the arrow 
keys. Withou t (~SHIFT) , works like right and left 
arrows; with ( SHIFT) , works like the up and 
down arrows. 

Cursor Positioning Commands 

( = ) - Typing ( = ) positions the cursor at 
the anchor. (The anchor is set at the location of 
the latest Adjust, Find, Insert, or Replace 
command. ) 

Find - Position the cursor after the specified target 
string. 

Jump - Position the cursor at the beginning, the 
end, or the specified marker. 



Page - Position the cursor 
current location. 



23 lines from the 
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Command Syntax and Semantics 

The Editor commands are presented in alphabetical order and described in a variety of formats to 
make them more useful to you. Each command's explanation includes: the command's name, a 
brief functional description, a diagram showing its legal syntax, the command's prompt (if any) 
and text which discusses using the command. Each of the command's options are also covered 
and some have examples to show the proper use of these options. 

Alphabetical Listing 
of Editor Commands 

Adjust 

Copy 

Delete 

Equals ( = ) 

Find 

Insert 

Jump 

Margin 

Page 

Quit 

Replace 

Set 

Verify 

eXchange 

Zap 
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ADJUST 

Adjust horizontally shifts the starting column of one or more lines of text 

I 



(m> 




repeat 

factor 



[ ~o 






<™> 



<s> 



Hs 



cursor wheel] 



(Backspace 



>> 



3 



■■ 1 »"f (Mw")( fBECiiT ri) J »H 



Item 



repeat factor 

Semantics 

The Adjust prompt: 



Description/Default 



integer numeric constant 



Range Restrictions 



1 thru 9999 



> Adjust: LJust RJust Center (arrow keys) C < e x c > to leave] 



The Adjust command provides a means of formatting text and enables you to make text more 
readable. Adjust uses the line position of the cursor when the command is entered as a starting 
point. A li ne-ori e nted c o mmand, Adj ust lets you shift an entire line of text to the left or right 
using the ( -> ) , ( <- ) , ( BACK SPACE 1 , or curs or whe el. Repeat factors can be used with these 
keys to shift the text. For example, pressing 7 ( -> ) results in the line of text shifting 7 spaces 
to the right. 



Pressing ( A ) (for Adjust) and then ( L ) , ( R ) or [ C ) moves the line to the left margin, 
right margin or centers the line between the two margins. The margins used by these options 
are the Right and Left margins currently set in the environment (see Set command). 



Typing a repeat factor and ( j ) or ( 1 ) causes that number of lines to be adjusted the same 
amount as the accumulated adjust ments at th at poi nt. The slash (/) functions as an infinite 
repeat factor and can be used with [ t ] and ( I ) . It causes adjustments to be made from 
the curre nt line to either the beginning or the end of the text file, respectively. For example, 
pressing ( C ) / ( I ) causes all the text between the current cursor position and the end of 
the file to be Centered according to the current margins. 
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Note 

Take care when using large repeat factors or the slash (/) character 
when adjusting text. This is because the effects of the Adjust com- 
mand cannot be aborted. Whatever adjustments are made become 
permanent unless the Adjust command is used again. 

Adjust also sets the anchor used by the Zap command. Pressing = (the Equals command) 
moves the cursor to the position of the last Adjust unless the anchor has been reset by either a 
Find, Insert, or Replace command. 

Leave the Adjust command by pressing ( Select ] ( ( EXECUTE ] ). The system stores the adjusted text in 
the computer's memory and the Editor prompt reappears. 
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COPY 

Copy inserts text from a specified file or from the copy buffer. 



<m> 



-Cs> 



volume | j 

spec i f icat ion 



f ile 
spec i f icat ion 



Ki> 



rO 



+£ ] J 1 — +{ [ Warn] or (ENTER) j- 



■Wl SUM | -( M ) ( [ SHIFT S - [ EXECUTE ] ) J 



Item 


Description/Default 


Range Restrictions 


volume name 


literal 


any valid volume name. 


file name 


literal 


any valid text file; do not enter .TEXT suffix. 


marker 


literal 


1 to 8 ASCII characters excluding CHR (0) thru CHR (31) 
andCHR(127). 



Semantics 

The Copy prompt: 

>Copy: Buffer File <sh-sel> 

The Copy command provides a way of moving or duplicating t ext in a file and copyi ng tex t 
from another file. These are the Buffer and File options. Pressing [ C ) (for Copy) and ( B ) 
(for Buffer) results in the contents of the copy buffer being written to your current text at the 
cursor position when the command was entered. The screen displays the new text and the 
Editor prompt. 

The copy buffer is filled with the text involved in the most recent Delete, Insert or Zap command 
and its contents are cleared with the Margin command. Margin clears the copy buffer regardless 
of the settings in the environment. Doing a Copy (from a File) also clears the copy buffer. A 
subsequent Copy from Buffer command generates the message: 



>ERRDR: Invalid copy, (space) continues. 
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Any subsequent Delete, Insert or Zap refills the buffer (destroying its previous contents) and 
copying from a file clears the contents of the buffer. However, doing a Copy (from Buffer) does 
not alter the buffer's contents. Neither do any cursor control movements or commands. There- 
fore, you can make multiple co pies o f the sa me text in different locations by repeatedly posi- 
tioning the cursor and pressing ( C ) [ B ) . 

To Copy from a file, press ( C ) ( F ) . The screen displays: 

> C o p y : File [marker >marker] ? 

The Editor is requesting a volume name, file name, and two marker names. The volume name 
may be omitted if the file in question is on the default volume. The volume (specified or default) 
must be on-line. Specification of the two previously set markers (see Set command) is optional 
but, if given, the marker names must be enclosed in square brackets and separated by a comma. 
Remember, only TEXT type files have markers. 

If markers are specified, only the text between those two markers is copied. If no markers are 
specified, the entire file is copied. Only one marker has to be specified. If it is the first marker (i.e., 
followed by a comma), the text is copied from the marker position to the end of the specified file. 
If only the second marker is given (i.e., preceded by a comma), the text is copied from the 
beginning of the specifed file to the position of the marker. The copy occurs at the cursor's 
position when the Copy comm and wa s enter ed. You can exit the command before all specifica- 
tions are complete by pressing [ SHIFT ) - ( Select ) . 



After typing the appropriate information and pressing ( Return ) or (ENTER) , the Editor displays: 

>Copv . . . 

This shows that the specified text is being copied into your current text. When the operation is 
complete, the Editor prompt reappears and the screen displays all or part of the text that was 
copied. 
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DELETE 



Delete removes text from the current file. 



<^>Y 



^-♦/ fiJaMpiitn ^ 




repeat 
factor 



■ fcaj) - 



— */ (niton) or (enter! 



( Backspace'] 



> 



-® 



<^> 






-*/spacebarV 



[cursor wheel) 



!»/ dateTl rt EXECl/fD ) J I~~H 

*— *{ flip-l SaUct ] ( 1 SHIFTl - flXECUTE ] ) 



Item 


Description/Default 


Range Restrictions 


repeat factor 


integer numeric constant 


1 thru 9999 

(1 thru 4095 for TAB) 



Semantics 

The Delete prompt: 



>Delete: < 



;MouinS c ommands > [<exo> ideletes> <sh-exc> aborts] 



The Delete command enables you to remove text and fills the copy buffer with the deleted text. 
Delete uses the cursor position when the command is entered as a starting point. Subsequent 
cursor movement by any cursor control key causes text to be removed between this point and 
the new cursor position. Text can be recovered by moving the cursor back toward the starting 
point. 
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Direction applies in the Delete command and is shown by ( >) (forward) or (< ) (backward) in the 
Delete prompt. If forward, movement occurs from the cursor toward the end of the file; if 
backwar ds, mo v emen t is from t he cursor toward the beginning of the file. Movement generated 
with the ( TAB ) , ( Return ) or [ENTER] , and space bar takes place in the direction shown. Direction can 
be changed while in the Delete command by pressing > ♦ or + (for forward) or < » or - (for 
backward). 



Repeat factors are availa ble wi thin the Delete command. For example, pressing ( D ) (for 
Delete) and then 9 ( Return ) [ENTER] will remove 9 lines of text in the current direction starting at the 
cursor position. 

Delete fills the copy buffer with the deleted text and thus provides a means of moving or 
duplicating text. See the example in the section "A Sample Editor Session". 



To exit the Delete command press ( Select ) ( ( EXECUTE ) ) or ( SHIFT ) - ( Select ) ( ( SHIFT ] - ( EXECUTE ) ). ( Select ) 
confirms the deletion, returns the Editor prompt and displays the cursor at its position when ( Select ) 
was pressed. ( SHIFT ] - [Select] aborts all changes made since Delete was entered, returns the Editor 
prompt and displays the cursor at its position when Delete was entered. 

No te that t he cop y buffer is filled by whatever is deleted; whether the command is exited with a (Select ) 
or ( SHIFT ] - ( Select ) makes no difference to the copy buffer. 
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EQUALS (=) 

EQUALS positions the cursor at the anchor's location. 

Semantics 

The equals sign ( = ) is a cursor positioning command. It moves the cursor to the beginning of 
the most recent item Adjusted, Found, Inserted, or Replaced. Pressing = causes the cursor to 
jump to the location of this "anchor" and the Editor's prompt is displayed. This is the anchor 
used by the Zap command. 
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FIND 



Find moves the cursor to an occurrence of a specified string. 



repeat 
factor 






delimiter 



target 
string 



delimiter 



<m> 



Item 



Description/Default 



Range Restrictions 



repeat factor 
delimiter 
target string 



integer numeric constant 

literal (see glossary) 

literal 



1 thru 9999 

any valid delimiter; must be used in matched pairs. 

1 thru 128 characters 



Semantics 

The Find prompt: 



or 



>FindC13: L <tar*et>=> 
>FindCi3: T <tarSet>=> 



The prompt displayed depends on whether the "Token" definition in the Editor's environment 
is set to true or false. If set to true, the first prompt is displayed; if false, the second is shown. 
These are explained below. 



In its simplest form, the Find command is executed by pressing ( F ) and specifying a string 
surrounded by delimiters. Upon typing the final delimiter, the cursor is positioned at the end of 
the first occurrence of the specified string in the current direction. 

The Find command moves the cursor and sets the anchor (used by Zap) at the location of the 
target string. In this context, a "string" is a contiguous series of non-control ASCII characters 
surrounded by delimiters. Delimiters are separators that signify to the Editor the beginning and 
end of the string such as the characters / ' . and > (more are listed in the glossary). 

Avoid using a delimiter that appears in your string. Delimiters must be matched pairs; if you use 
* to signify the beginning of a string, you must use $ to signify the end of the string. The 
maximum length of a target string is 128 characters. 

The Find prompt shows the current direction. When searching for a string occurence, Find 
looks for that string between the cursor position when the command was entered and either the 
end of the file (if direction is forward >) or the beginning of the file (if direction is backward < ). 
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Repeat factors are available with the Find command but must be typed before the Find 
command is initiated. If a repeat factor is used, the Editor positions the cursor at the end of that 
occurrence of the string. For example, typing 8 [ F ) /the/ results in the cursor being 
positioned at the end of the eighth occurrence of the. The slash (/) operates in a similar way 
but signifies the last occurrence of the specified string in the current direction. If no repeat factor 
or slash character is specified it defaults to the value 1 and the Editor attempts to find the first 
string occurrence. The Find prompt displays this value in square brackets. 

After pressing ( F ) , the prompt on your screen contains either an L or T for "literal" or 
"token" modes. Literal and token are interdependent; if one option is shown as available, the 
other is automatically the default. If L is shown in the prompt and you want to use the token 
search mode, simply type in the target string surrounded by delimiters. The search will take 
place in the default mode (in this case, token). To do the same search in the literal mode, press 
[ L ) then type in the string as before. The Find command then searches for a literal form of 
the string. 

A literal string is exactly that — a literal string of characters either isolated or imbedded in a 
word or paragraph. A token string is one which is isolated by delimiters. Delimiters in this 
context are any ASCII characters except numbers or alphabetic characters. Blanks are common 
delimiters in English text because they separate words. 

To illustrate literal and token searches, the following example assumes the direction is forward 
(>) with the cursor located at or before the start of the sentence shown. In the sentence 
That's my hat!, a token search for h a t moves the cursor behind the last word h a t in the 
sentence whereas a literal search for hat moves the cursor behind the hat imbedded in 
That 's. 

The "same" option is another feature of the Find Command. Same refers to the most recent 
target s tring u sed in either the Find or Replace command. Suppose you typed the sequence 
( F ) ( L ) *3alactic*. After pressing the final delimiter (*), the Editor mo ves th e cursor 
behind the first literal occurrence of the target string sfalactic. Then typing ( F ] ( L ) 
( S ) results in the cursor moving behind the next literal occurrence of the same target. 

When using the "same" option with the direction set backward (< ), use a repeat factor of two 
before initiating the Find. Otherwise, the Editor finds the previous occurrence since it searches 
between the cursor's current position and the beginning of the file. 

Suppose after the first Find your screen displays: 



<Edit: Addst Cpy Dlete Find Insrt Jmp Rplace Quit XchnS Zap ? 

AccordinS to the Sa lactic archiuest the 
interSalacti c_c ruisers continued their 
explorations without reSard for 
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If you press ( F ] ( L ) ( S ) to Find the same literal string, t he cur s or pos it ion on the screen 
does not change. To find the next occurrence, type 2 then press ( F ) ( L ] ( S ) . Since the 
direction is backwards and the Find command always positions the cursor behind the target 
string, using a repeat factor of 2 skips to the next effective occurrence of the literal Galactic. 
Repeated searches in the forward (>) direction operate in a straightforward manner. 



Note 

If a Replace has been done since the last Find operation, the target 
string used by the "same" option is now the target specified in the 
Replace command. 

Searches are sensitive to the case of the characte rs (up per a nd low er case) unless Ignore case and 
Token are set to T rue in the Environment. Type ( S ] a nd ( E 1 t o Set the Environment. Type 
( I ) and [ T ) to set Ignore case to True. Type ( T ) and ( T ) if Token is not already True. 
After these two conditions are met, the Editor treats both the target string and each token string as 
uppercase. 

Find is one of the commands that sets the anchor used in the Zap command and accessed by the 
Equals command. 



( SHIFT ) - fSelecT) ( ( SHIFT ) -( EXECUTE ) ) ca n be used to abort the Find command before all specifica- 
tions are co mplete . If ( SHIR ) - [Select] is used, the target pattern used by the "same" option remains 
unchanged. ( Select ) cannot be used with the Find command. The command is executed immediately 
when the final delimiter (or [ S ) if "same" is used) is typed. 
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INSERT 

Insert opens a window in the current file for the subsequent insertion of text. 

I 



\M)—f 



— M Qnwft chir) j I* 



non-control 
ASCII character 



He 



ml [ Backspace ) ) ^ 

h/®) 



cursor wheel 
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Item 


Description/Default 


Range Restrictions 


non-control 
ASCII character 


literal 


Any valid ASCII character excluding: CHR (0) thru CHR 
(31)andCHR(127). 



Semantics 

The Insert prompt: 

> I n s e r t : Text < b s > i <clr ln> [ < s e 1 > a c c e p t s » <sh-sel> escapes] 

The Insert command opens a window in th e text file directly in front of the cursor position for 
text creation. When initiated (by pressing ( I ) or [ INS CHR ) or (INS LN) ), the text from the 
cursor to the right edge of the screen is shifted to the right. Insertion always takes place directly 
in front of the cursor location when Insert was entered. Any sequence of non-control ASCII 
characters may be inserted and any cursor control key may be used. However, unless the 
movement generated by the curso r control keys is backward, the y produce question marks (?) 
in the text. You can ( BACK SPACJT) to delete a character or press ( CLR LN ) to delete the most 
recently inserted line. [ CLR LN ) is available only after a line of text has been inserted. Back- 
spacing past the point at which Insert was entered is not possible. 
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The way in which text insertion takes place depends on flags or parameters set in the Editor's 
environment. These flags have default values supplied by the Editor but can be changed with the 
Set command. The ones that concern you here are Filling and Auto indent. These two options 
generally have opposite values. Most of what you need to know about Filling and Auto indent can 
be summed up in one sentence: If you are writing program source text, set Filling to false and 
Auto indent to true; if writing regular text, set Filling to true and Auto indent to false. 

Filling, when set true, performs both "wrap around" and "margining" functions. As inserted text 
approaches the Right margin (another environment option), the Editor attempts to fit the words 
on the current line. If a word would cause the line to extend beyond the right margin, it is 
automatically shifted to the next line (i.e., th e syst e m supplie s a carriage return and a line feed). 
When the insertion is completed by pressing ( Select ) ( ( EXECUTE ) ), all text following the cursor in the 
current paragraph is margined. Margining adjusts the text to fit between the environment's 
margins and also compresses blanks in the text. You can have two blanks following the four 
characters: ? . : ! . All other blanks are compressed into a single blank character. 

Note that the Editor's definition of a paragraph is ANY text delimited by any combination of 
blank lines, lines having the Command character as the first non-blank character in a line, or the 
beginning and end of a text file. The Command character is yet another of the environment's 
options; see the Set command for more details. 

Note 

As the definition of a paragraph infers, the Editor does not disting- 
uish tables from other kinds of text material. Any insertions within a 
table will result in the table being margined (i.e., c ol lapsed) if Filling 
is set to true and the insertion is exited with (Select) ( ( EXECUTE ) ). Use 
the S et command t o set Filling to False before inserting in a table or 
list. ( ( SHIFT) - (Select ) will NOT restore the text to its original state after a 
paragraph has been margined). 

If Filling is false, a beep is generated as you approach the end of the line, signaling you to press 
( Return ) or (ENTER) the same way a bell on a typewriter does. If you continue to insert text past the 
last visible column on your screen, the Editor accepts the characters and shows you that they are 
outside of the display area by placing an exclam ation p oint (!) in t he final column. To access these 
characters, complete the inserti on by pressing (Select) (( EXECUTE )), p osition the cursor before the 
last word on the line and press ( I ) followed by (Return) or (ENTER) to insert a carriage return. 
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If Auto indent is true, pressing ( Return ) or (ENTER) automatically places the cursor in the same 
starting column as the previous line. When Auto indent is false, the cursor is positioned according 
to either the Left or Paragraph margin in the environment. 



If Insert is exited with (Select ) ( ( EXECUTE ) ) (and Filling is true and Auto indent false), all text 
following the insertion in the same paragraph is margined according to the Right, Left and 
Paragraph margin values in the environment. Also, the entire insertion is stored in the copy buffer 
so you can copy the same text elsewhere if you wish. If Insert is exited with ( SHIFT ) - (Select ) 
(regardless of the options set), all changes are aborted and the text and cursor appear as they did 
when the command was entered. 

The Insert command sets the anchor (used by the Za p comm an d) at the positi on where Insert was 
initiated. The anchor is set regardless of whether ( Select ) or ( SHIFT ) - [ Select ) is used to exit the 
command. 



The Editor 87 



JUMP 



The Jump command repositions the cursor. 




-<m> 



J 



•/ (Rdum) or f ENTER) J »■ 



»/ ( Shift ) - ( Sttot ) 



( (SHIFT ) - I EXECUTE I) ] 



Item 


Description 


Range Restrictions 


marker 


literal 


1 to 8 ASCII characters excluding: CHR (0) thru CHR (31) and 
CHR (127). 



Semantics 

The Jump prompt: 



>JUMP:: Besfin End Marker <sh-sel> 



The Jump command moves the cursor to the beginning or end of a text file or to a previously 
defined marker. The command ha s no o t her eff ects; it merely repositions the cursor. To Jump 
to the beginning of your file, press ( J ] [ B ) . To Jump to the end of your file, press ( J ) 

CXI. 



You can also Jump to a marker by p ressing ( J )( M ) and typing the name of any previously 
set marker in the file followed by ( Return ) or [ENTER] . Marker names are defined with the Set 
command. A legal marker name is any sequence of up to eight non-control ASCII characters 
(control characters are deleted by the system). They can actually be longer than this but the 
Editor only pays attention to the first 8 and truncates the rest. 

Also, marker names are not case sensitive. The Editor converts all marker names to uppercase 
letters so they can be typed using any desired combination of uppercase and lowercase letters. 
There is a 10 marker limit per text file. See the Set command for more information on markers. 
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MARGIN 

Margin formats all text in the current paragraph to fit the margins set in the environment. 



(cd) -h 
Semantics 

Margin is disabled and the system generates an error message unless the environment's Auto 
indent is false and Filling is true when the command is executed. 

The Margin command provides a means of formatting paragraphs in your file. A paragraph is 
defined by the Editor to be ANY text delimited by any combination of blank lines, lines having 
the Command character as the first non-blank character in a line, or the beginning and end of a 
text file. See the Set command for details on the Command character. 



Upon initiating Margin (by pressing ( M ) ), the Editor takes all the text in the current para- 
graph (the one where the cursor is) and forces it to fit within the Left, Right and Paragraph 
margin boundaries of the environment. After margining, the first line of the paragraph begins at 
the column specified by the Paragraph margin setting and the rest of the text conforms to the 
Left and Right margin settings. If a word would exceed the Right margin it is "wrapped around" 
to the next line. 

Two blanks are allowed following the four characters: ? . : ! . All other blanks are compressed 
into a single blank character. 

Since the Command character in the environment delimits a paragraph, you may want to use it 
as the first character in each line of tables or lists which you do not want margined. See the Set 
command for more information on the Command character. 

Note 

If a table or list fits the definition of a paragraph, the Margin command 
will de fi nitely mar gin that text. Exiting the Insert command with 
( Select ) ( ( EXECUTE^ ) also uses some of the Margin routine so be aware 
that these commands can potentially "collapse" a table or list. 



The Margin command has no parameters and its effects cannot be aborted. When writing 
program text or tables, it is advised that Auto indent be set true, Filling be set false and the 
Paragraph margin be equal to the Left margin. 



Note 

The Margin command clears the contents of the copy buffer regard- 
less of the settings of the Auto indent and Filling options. 
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PAGE 



Page moves the cursor one or more pages (23 lines) in the current direction. 



L 






repeat 
factor 



y»- (cxd) -^ 



Item 


Description/Default 


Range Restrictions 


repeat factor 


integer numeric constant 


1 thru 1000 



Semantics 

The Page command lets you move rapidly through a text file by repositioning the cursor one or 
more pages (23 lines of text) forward ( >) or backward (< ) in a file. Page is executed by pressing 
( P ) and its movement occurs relative to the position of the cursor. Page moves the cursor in 
the direction displayed by the Editor prompt when the command is entered. The direction can 
be changed by pressing > . or + for forward or < > or - for backward. 

Repeat factors are available in the Page command. For example, to move the cursor 3 
"screens" or pages in the file, pre ss 3 f~P~) • The slash character (/) can be used in place of an 
integer repeat factor. Pressing / ( P ) results in the cursor moving to the end of the file (if 
direction is >) or the beginning of the file (if direction is < ). If neither repeat factor nor slash is 
specified, the default is 1 and the cursor moves one page. 



( Select ) ( ( EXECUTE ) ) and [ SHIFT ) - ( Select ) ( ( SHIFT ) - f~EX~ECUTE ) ) are not available in the Page command. 
The command is immediately executed when ( P ) is pressed. 
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QUIT 

QUIT leaves the Editor with various exit options. 



(m> 



^(m> 



"<m> 



<55> 



r~i 



— -QCKJJ— » name — *^_^^or^^ 



-<OD> 



Semantics 

>Quit : 

Update the work file and leave 

Exit without updating 

Return to the editor without updating 

Write to a file name and return 

Save as file new file BINSEARCH . TEXT 

Overwrite as file BINSEARCH , TEXT 

The Quit command allows you to exit the Editor and store your file on a mass storage medium. 
The last two quit options shown above are only available if the file existed before the editing 
session. 



Quit is initiated by pressing ( Q ) from the Editor's prompt. Choose any of the options displayed 
by pressing the first letter of the option. 



Pressing ( U ] (for Update) results in the contents of the text in the computer's memory being 
written to a text file on the system volume under the name WORK .TEXT. This workfile may or 
may not be associated with another file name (see the Get and Save commands in the Filer 
chapter). After writing the file, the system reports the file's size (in number of bytes and blocks) 
and displays the main command prompt. 



Pressing [ E ) (for Exit) either immediately exits to the main level or displays: 

Are you sure you want to exit without updating? 
Type Yes to Exit without update 
Type No to Return to Editor 



This message is displayed only if changes have been made to the text file in the current editing 
sessio n. If no changes have been made, the system immediately goes to t he ma in level when 
[ E ) is p ressed. It also exits to the main level if you respond by pressing ( Y ) . Responding 
with ( N ) returns you to the Editor. 
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Pressing (~R ) (for Return) returns you to Edit mode with the cursor located where it was when 
Quit was entered. 



Pressing ( W ] (for Write) causes the system to prompt you for a file name. A complete file 
name is needed. If a volume ID is not given, the default volume is used. The volume PRINTER: 
may be specified. This results in the file being listed to the printer. 

If you use the Write option and the file already exists, the Editor displays this prompt: 

>Quit : 

FILE. TEXT exists . . . 

Rewrite then purse old 

Overwrite 

Purse old then rewrite 

None of the aboue 

Rewrite then purge old is like the Save command. An attempt is made to write the new file before 
purging the old. 

Overwrite removes the original file and then attempts to write the new version in its place. On 
SRM units, duplicate links and passwords will be preserved. On a disc, the file may not fit if the 
new version is larger than the old. 

Purge old then rewrite removes the original file and then attemps to write the new file in the 
biggest space on the disc. This alternative gives you the best chance that there will be room for the 
new file. 

Whether you "Overwrite" or "Purge old then rewrite", the original copy of the file is gone and 
the only copy of the file is in the Editor's memory. It is advisable to save it on another disc as soon 
as possible. 

None of the above returns you to the Editor. You may Quit again and write the file with a different 
name. 



Pressing ("" S ) (for Save) results in the file being written to the original volume and file. 

If you try to Save a file and you get the message: 

>ERR0R: No room on vol <space> continues. 

Press the spacebar to continue. You could put in another disc with enough space, then Quit and 
Save it on the new disc. Alternatively, you can Quit and Overwrite the file. 



Pressing (~ ) (for Overwrite) is designed for SRM systems. The Overwrite option allows all 
duplicate links and passwords to remain accurate. On a disc, Overwrite may not work if the file 
has been enlarged. If this happens, press the spacebar to continue, Quit and Save again. The 
previous Overwrite removed the original file. Now the Save will try to save the file in the largest 
space on the disc. If this does not work, you must put the file on another disc. 
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REPLACE 



Replace does one or more substitutions of a specified string for another string. 



I r-Vi I 'GIB 1 ^-^ A I ^-^ I 



^ (ctd) -^ 



delimiter 



target 
string 



delimiter 



<m> 



delimiter 



substitute 
string 



delimiter 



<m> 



Item 


Description/Default 


Range Restrictions 


repeat factor 


integer numeric constant 


1 thru 9999 


delimiter 


literal (see glossary) 


any valid delimiter; must be used in matched pairs. 


target string 


literal 


1 thru 128 characters 


substitute string 


literal 


1 thru 128 characters 



Semantics 

The Replace prompt: 

>ReplCi]s L 
or >ReplCl]: T 



V < t a r 3 > < s u b > = > 
U < t a r 3 > < sub > = > 



The prompt displayed depends on whether the "Token" definition in the Editor's environment 
is set to true or false. If true, the first prompt is displayed; if false, the second is shown. These are 
explained below. 

The Replace command allows you to substitute one string for another in your text file. The 
anchor (used by the Zap command and accessed by the Equals command) is set at the location 
of the replacement. Replacements can be done to a single, all, or only certain occurrences of a 
string. 



In its simplest form, the Replace command is executed by pressing [ R ) and specifying two 
strings — a target and substitute — each surrounded by delimiters. The target and substitute 
strings may be different sizes. Upon typing the final delimiter, the first occurrence of the target 
string is replaced by the substitute string and the cursor is positioned at the end of the substitu- 
tion. 

A target string (the one that you want replaced) must be supplied. A string is a contiguous 
series of non-control ASCII characters surrounded by delimiters. Delimiters signify the begin- 
ning and end of a string and are characters such as: / ' ♦ and > (more are listed in the 
glossary). 
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A substitute string (what you want the target string changed to) must also be supplied with 
delimiters. The substitute may be an empty (null) string. 

Avoid using a delimiter that appears within your string. Delimiters must be matched pairs, i.e., if 
you use * to signify the beginning of a string, you must use $ to signify its end. The substitute 
string can have a different set of delimiters than the target string and the two strings may be of 
different sizes. The maximum length of either string is 128 characters. 



After pressing ( R ) , the prompt on your screen contains either an ( L ) or ( T ) for 
"literal" or "token" modes. Literal and token ar e inter dependent; if one option is shown as 
available, the other is automatically the default. If ( L ) is shown in the prompt and you want 
to use the token search mode, then type in the two strings and their delimiters. The replacement 
takes place in the default mode, in this case, token. To do the same replacement in the literal 
mode, press ( L ) and type in both strings as before. The Replace command then searches for 
a literal form of the string. 

A literal string is exactly that — a literal string of characters either isolated or imbedded in a 
word. A token string is usually a word (a string isolated by delimiters). Delimiters, in this 
context, are any ASCII characters except numbers or alphabetic characters — they do not have 
to be matched pairs. Blanks are the most common delimiters in English text because they 
separate words. 

To illustrate literal and token replacements, the following example assumes the direction is 
forward ( > ) with the cursor located at or before the start of the sample sentence. In the sentence 
That's my hat!, a token replacement for h a t with umbrella replaces the last word hat 
in the sentence with umbrella whereas a literal replacement would substitute umbrella for 
the hat imbedded in That 's (resulting in Tumb rel la 's my hat!). 

Direction applies in the Replace command and is shown by the first character in the com- 
mand's prompt. If the direction is forward (>), the replacement occurs between the cursor 
position and the end of the file; if backward (< ), between the cursor and the beginning of the 
file. 

Repeat factors are available for the Replace command but must be typed before the command 
is initiated (before ( R ) is pressed). A repeat factor causes that number of substitutions to be 
made. If not specified, the repeat factor defaults to 1. A slash character (/) may also be used to 
change all occurrences of the specified string in the current direction. The repeat factor (or slash 
character) is displayed in brackets C ] in the command's prompt. The repeat factor works 
differently when the Verify option is used. 

The Verify option lets you choose whether or not to make a particular replacement. The 
combination of a repeat factor with Verify allows you t o replac e only certain occurences of a 
string in the file. For example, after pressing 2 ( R ) ( V ) and typing in the target and 
substitute strings, the Editor moves the cursor to the first occurrence of the target string and 
prompts: 

>Rp1C2]s <sh-exc> aborts^R replaces*' ' doesn't 
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To confirm the replacement, press ( R ) . To skip to t he nex t replacement (if any), press the 
space bar. While using Verify, pressing ( SHIFT ) - fSelecp ( ( SHIFT ) - fEXECUTE ) ) aborts the operation 
and retains all replacements made up to that time. 

The "same" option is available with Replace and refers to either the most recent target string 
(used in a Find or Replace) or the most recent substitute string (used only in Replace). Which 
string it signifies (target or substit ute) depends on where it is used in the Rep lace co mmand. To 
use "Same", simply press ( S ) in place of the delimited string. If you type ( S ) followed by 
a delimited string, the most recen t target is replaced with the specified string. If you type a 
delimited string followed by ( S ) , t he spe ci fied ta rget is replaced with the last substitute. Both 
strings may be specified by typi ng f~~S~) [ S ) . The current assignments of the "same" 
patterns can be seen by pressing ( S ) ( E ) (see the Set command for more details). 



Note 
If a Find has been done since the last Replace, the target string used 
by the "same" option is now the target specified in the Find com- 
mand. 



The "Ignore case" optio n ap plies to the Replace command. Type ( S ) a nd ( E ) to Set the 
Environment. Type ( I ) and ( T ) to set Ignore case to True. Type ( T ) and ( T ) if Token 
is not already True. The target string and all token strings in the text are treated as upper case. 
When a match is found, the token string is replaced with the substitute string. The case of the 
substitute string is not affected by the Ignore case option. 

The R e place c omma n d can be aborted before all specifications are complete by pressing 
(SHIR) - (Select) ( ( SHIFT) - fEXECUTE ) ). (Subsequent use of the "same" option after aborting the 
Replace command may give you unwelcome results). 
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SET 



Set defines markers and alters the environment in which your text operations occur. 



(s> 



-<ED-j 



-<t£>~ 



-/a) — ' 



-H en 



< 



*\ (Hrtum) or [ EWTEHl 



> 



-<sD i i •(m)-' 



-♦(spacebar) j— *■ 




(spacebar) ■ - 



^-•4 (RMjrn) or lEHTEB] J ^ 



nan-control 
ASCII character 



U(cE5> 



»f[ Sllilt 1- CSeiecTl ( f SHIFT ) - ( ElECUTEl l V 



Item 


Description/Default 


Range Restrictions 


Recommended Range 


marker 


literal 


1 to 8 ASCII characters 

excluding CHR(O) thru 

CHR(31)andCHR(127) 




margin integer 


integer numeric constant 


thru 9999; left margin 


thru 49 for 






must be less than right 


50-column displays; 






margin 


thru 79 for 80-column 
displays 


non-control ASCII 


literal 


any valid ASCII 


- 


character 




character excluding 

CHR(0)thruCHR(31) 

and CHR(127) 





Semantics 

The Set prompt: 

>Set: Env MrK Pros Doc <sh-sel> 
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Set lets you define markers and various environ ment p a rmete rs. Markers are Set by moving the 
cursor to where you want t he ma rker, press ing ( S ) ( M ) (for Set Marker) and typing in a 
marker name followed by ( Return ) or [ENTER) . A marker name is any sequence of up to eight 
non-control ASCII characters. The Editor accepts more than eight characters but truncates 
anything longer. All non- printing characters (those with an ASCII value of either 127 or in the 
range of to 31 ) are deleted by the system. The Editor converts these names to uppercase so they 
can be typed in whatever form is convenient. 

No more than ten markers can be set in a file. If you attempt to set more than ten, the Editor 
displays the markers in a numbered list and prompts you for the number of the marker you wish 
to replace. All markers can be removed by giving the Zap marker command. Markers are used 
with the Jump and Copy commands and their names are shown in the environment display. The 
locations of the markers are not shown so the use of meaningful marker names is advised. 



Pressing ( S ) ( E ] (for Set Environment) displays the current environment and allows you to 
change the environment's parameters. When entering the Editor with a new file, the default 
environment is the Program environment which looks like: 



>Enu i ronment : {options} <sel> or <sp> leaves 



Auto indent 
Fi 1 1 ins 
Left ma r Si n 
R i S h t m a r 3 i n 
Para ma rsin 
Command oh 
Token def 
I sno re case 
Zap markers 
275 bvtes used 

Patterns: 

<tarSet>= 'i 

Ma rKe rs : 
TOP 



True 

False 



78 
5 

True 
False 

• 34B909 available. 



<subst>= 'inary 



FIX 



File 

Date 



BINSEARCH.TEXT 
Created: 10-11-8; 



Last Used: 10-11-82 



Patterns and Markers are only shown if they have been set. The heading near the bottom displays 
a file name if the Editor is entered with a specified file. Whenever a file is saved on a mass storage 
medium, the current environment is saved with it and becomes the default environment when 
that file is used by the Editor. 
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The environment also displays how many bytes of memory have been used and how many are 
still available for use in the Editor. The total number of bytes (used and available) depends on the 
amount of memory in your machine. 

To change a parameter in the environment, press the first letter in the parameter's name. The 
cursor is automatically positioned at the item to be changed and the new value must be typed. If 
the parameter needs a number (as in Left , Right and Paragraph margins), then the number must 
be followed by pressing ( Return ) or (ENTER) or the space bar. All other parameters accept a single 
character and return the cursor to the environment's prompt as soon as the character key is 
pressed. 

Automatic indenting is a boolean (with either a true or false value) whic h affec ts t he Inse rt and 
Margin commands. When inserting text with this item set true, pressing ( Return ) or (ENTER) auto- 
matically moves the cursor to the next line at the same starting column as the previous line. This 
indenting feature is useful when writing Pascal programs so it is set true for the Program (default) 
environment. 

When Aut o inde nt is true the Margin command is disabled. When Auto indent is false, pressing 
(Return] or (ENTER) places the cursor on the next line at either the Left margin or Paragraph margin 
(as currently defined in the environment). 

Filling is another boolean value which affects the Insert and Margin commands. It usually has a 
value opposite that of Auto indent. When set true (and auto-indent is false), filling causes 
automatic "wrap around" of text. If a word is too long to fit on the current line (as defined by the 
Ri ght ma rgin value), it is carried or wrapped around to the next line and no carriage return ( (Return) 
or (ENTER) ) is necess ar y. Anoth er effect of this parameter being set true is that an Insert completed 
by pressing ( Select ) ( ( EXECUTE ] ) causes all text following the insertion in that paragraph to be 
margined or filled according to the current values of the Left, Right and Paragraph margin 
settings. All blanks in the text are then compressed to a single blank (though two blanks are 
allowed following the characters: ? . ! :). The Margin command only works when Filling is set true 
and Auto indent is set false. 

With Filling set false, the wrap around and margining functions are disabled. When app roach ing 
the en d of a line, the system generates a "beep" to inform you that you need to press ( Return ) or 
(ENTER) to go to the next line. If you type past the display area of the screen, an exclamation point 
(!) is shown in the last column. The text, though not visible, is maintained in the computer's 
memory. 

The Left margin may be set to any integer between and 9999. Numbers longer than 4 digits are 
truncated by the system. The Left margin must be less than the Right margin setting or an error 
message is generated when you attempt to exit the environment. 

The Right margin setting has the same numerical limitations as the Left margin. Unless you have 
a particular reason for doing so (like making full use of a 132 column printer), it is not a good idea 
to set this margin beyond the right column display limits of your screen because the text will not 
be visible. 
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The Paragraph margin can be set to any positive integer up to 4 digits. This setting determines 
the indention that the first line in each "paragraph" will get. This occurs when Filling is set false 
(while inserting text) or when Margin is used. Note that a paragraph as defined by the Editor is any 
text surrounded by blank lines or by lines beginning with the Command character (discussed 
below). The beginning and end of a file will also delimit paragraphs. 

The Command character can be any non-control ASCII character. If this character is the first 
non-blank character in a line, the Margin command treats the line as if it were blank. The line is 
not margined and it is considered to be the beginning or the end of a paragraph. The default 
Command character is the ( A ) character. 

Token is a boolean used by the Find and Replace commands. When Token is set true, the default 
value for Find or Replace becomes token and the command's prompt displays the literal option. 
(Token and literal refer to the type of target string searches that take place in these commands). 
Conversely, if Token is false, the default value for Find and Replace is literal and the command's 
prompt displays token as an option. 

The Ignore case command affects searches in the Find and Replace commands. If "Ignore case" 
is left as False, then "string" and "STRING" and "String" are not treated as equal. If "Ignore 
case" is set to True, they are treated as equal. This only works when the Environment's Token 
mode is True or if you type a "T" before typing the target string. 

The Zap markers command removes all markers from the file. 

The e n vironm e nt display is left and the Editor's main prompt returned by pressing (Return) or 
(ENTER) , ( Select ) ( ( EXECUTE ) ), or the space bar. The current environment settings are automatically 
saved with your file when the text is written to a disc or other mass storage medium. 

Although there is only a single environment associated with a text file, the environment may be 
set to one of two predefined configurations: the Progr am en v ironm ent (by pressing ( S ) 
( P ) ) and the Document environment (by pressing ( S ) ( D ) ). These configurations 
optimize the various environment parameters for writing programs or regular (non-program and 
non-tabular) text, respectively. When either predefined environment is Set, the current environ- 
ment is displayed and a n y of its parameters can be changed. If you want to change just one or two 
parameters, use ( S ) ( E ) to get into the existing environment. 

Changes made to the environment cannot be aborted but the parameters may be changed as 
many times as desired. 



The Editor 99 



VERIFY 

Verify refreshes the screen display from memory. 



Semantics 

The Verify command has no options; it is executed immediately by pressing ( V ) . Verify 
causes the Editor to refresh or update the current screen display from memory, move the 
current line (the one where the cursor is) to the middle of the screen, and display the Editor 
prompt. If the cursor is located in the first 23 lines of text when Verify is used, the line containing 
the cursor is not moved. 
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eXchange 

eXchange replaces text character for character at the cursor position. 



(m> 



I 



non-con tro 1 
ASCII character 



•■(cursor wheelV 



*\ (Backspace ] V- 



•(spacebar)- 



<^> 



<S> 



<S> 



<S> 



■/ ( select nriiiiaiTn ] \- 



r* 



^-^lMj-(JeleMj ( CUD - ( EXECUTE I i) ' 



Item 



non-control 
ASCII character 



Description/Default 



literal 



Range Restrictions 



any valid ASCII character excluding: CHR (0) thru CHR 
(31)andCHR(127). 
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Semantics 

The eXchange prompt: 

>Xchnsfe: Text <bs> <sh-sel> aborts <sel> accepts 

The eXchange command lets you exchange the text in a line on a character-for-character basis, 
beginning at the cursor position. Typing a character overwrites the character at the current cursor 
position and moves the cursor to the next character to the right. Us in g the horizontal cursor- 
positioning keys is also allowed: backspacing (such as with ( Backspace] , ( 4 ) , or cursor wheel) 
moves the cursor backwards and restores the original character; forwardspacing moves the 
cursor over the existing characters without changing them. 

The exchange command operates only on the current line (i.e., the line where the cursor is 
located when the command is entered). Attempting to move the cursor vertically will generate 
question marks that overwrite the existing characters. Backspacing past the point at which 
eXchange was entered is not allowed. 

Almost any ASCII character can be used in eXchange; however, use of control characters is not 
advised. Carriage returns cannot be entered, since you are not allowed to cross line boundaries 
while in the eXchange mode. Direction and repeat factors do not apply to this command. 

eXcha nge is ini tiated by pr essing ( X ) and is exited by pressing (Select) ( ( EXECUTE j ) or ( SHIFT ) - 
( Select ) ( [SHIFT) - ( EXECUTE ) ). ( Select ) c onfirm s the exchan ges, re t urns th e Editor prompt, and dis- 
plays the cursor at its position when [ Select ) was pressed. ( SHIFT ) - ( Select ) returns the copy of the text 
file in the computer's memory to its state before eXchange was entered, displays the Editor 
prompt and shows the cursor at its position when eXchange was entered. 
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Zap 

Zap deletes text and fills the copy buffer with the deleted text. 



Semantics 

The Zap command has no options; it is executed immediately by pressing ( Z ) . Zap deletes 
all text between the "anchor" and the current cursor position and stores it in the copy buffer. 
The anchor is located at the position in the text where the most recent Adjust, Find, Insert or 
Replace command was executed. (You can confirm the position of the anchor with the Equals 
command, which moves the cursor to the anchor). 

If more than 80 characters are going to be Zapped, the Editor displays a prompt asking if you 
wish to Zap anyway. Also, if the Copy buffer is not large enough to store the deletion, a prompt 
asks if you wish to go ahead and Zap the text. (Use the Set environment command to see how 
much memory is available; the copy buffer shares this memory with that used to hold the text 
file in memory). 

Recovery of the deleted text is achieved with the Copy (from buffer) command. Zap can also be 
used to move large chunks of text from one location to another within a file. 

Note that the effects of Zap can be surprising since the anchor position is set by four different 
and commonly used commands (listed above). Therefore, it is a good practice to check the 
location of the anchor (using the Equals command) before executing a Zap. 
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The Filer 



Chapter 



Introduction 

This chapter documents the use of the Workstation Filer subsystem. The Filer lets you manipulate 
files in various ways, including creating, listing, duplicating, and deleting files. The Filer can handle 
files on devices with various directory structures and physical characteristics. 

Before you read this chapter, you should read "The File System" chapter which defines basic 
concepts such as files, volumes, and directory organizations. 

There are four main sections in this chapter. 

• The first two demonstrate how to enter and use the Filer by leading you through a sample Filer 
session which uses the more common Filer commands. 

• The next section, "A Closer Look," presents detailed information about the Filer and its 
operation. 

• The "Filer Commands" section contains an overview or summary of all the Filer commands 
(useful for quick reference once you are familiar with the Filer), and a semantic and syntactic 
description of each Filer command, presented in alphabetical order. 

Any questions you have about commands covered in the sample session should be answered in the 
commands section. 
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Entering the Filer 



If your system is not already "up and running", refer to Chapter 1 for information on loading 
the Pascal System. The following prompt must appear on the top line of your screen before you 
can enter the Filer: 



Command: Compiler Editor Filer Initialize Librarian Run eXecute Version ? 

The prompt tells you that you are at the system's Main Command Level — the level from which 
all the Pascal subsystems (Compiler, Editor, Filer, etc.) are entered. Entry is accomplished by 
typing the uppercase character of the subsystem you wish to enter (for instance, R for Run and X 
for eXecute). 

Insert the disc labeled ACCESS: and press the ( F ) key. You can use either uppercase or 
lowercase letters when typing commands at the Main Command Level. However, letter case is 
important when typing file names. The screen displays: 



LoadinS 'ACCESS : FILER ' 



You can use the Permanent command (from the Main Command Level) to keep the FILER 
code file in memory if you wish. This will allow faster access to the Filer but uses more memory. 
Chapter 1 explains how to "permanently load" the Filer. 

The Filer Prompt 

The screen clears and displays the Filer prompt on the top line: 



Filer: ChanSe Get Ldir New Quit Remove Save Translate ','ols What Access Udir? 



You are now in the Pascal Filer subsystem. The Filer prompt shows the most common com- 
mands used in the Filer and "prompts" you to give the subsystem a command. 



The prompt shows only a partial list of the available commands; to see the others, type ( ? ) . 
The prompt line shows the Filer's alternate prompt: 



f 



Filer: Bad-sees Ext-dir Krunch Make Prefix-vol Filecopy Duplicate Zero ? C3.0] 



The alternate prompt displays the revision number of the Filer in brackets. Type ( ? ) again 
and the main Filer prompt reappears. 
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All Filer commands are initiated by typing a single key corresponding to the first character of the 
command shown in the Filer prompt. Uppercase and lowercase command characters are treated 
as equivalent by the Filer, so the keys may be typed in whatever form is convenient. 



Filer operations can be a borted by ty p ing ( SHIFT ] -fSelect ) ( ( SHIFT ) - ( EXECUTE ) ) when a single 
character is expected and ( SHIFT ) - ( Select ) ( Return ) or (ENTER] in place of a file specification. 

Filer Operations 

All of the commands in the Filer operate in one of two ways: the Filer either performs the 
operation immediately (when you press the letter key for that command) or it requests the 
information it needs to perform the operation and then does it. The request is generally for a 
volume specification or a file specification since all of the Filer's commands (except Quit) operate 
on volumes, directories and files. 

A volume specification identifies a particular volume. This can be done by supplying any of the 
following: the name of the volume; its associated unit number; a colon ( : ) to specify the default 
volume; or an asterisk (*) to specify the system volume. A file specification consists of both a 
volume specification and a file name; it completely identifies a particular file. All file specifications 
include a volume specification even if by default. If the volume specification is omitted and only 
the file name is given, the Filer looks for a file of that name on the default volume. 



A Sample Filer Session 

Work through the following examples on your machine as you read through this section. 
Interacting with the computer will teach you more about the Filer than just reading the material. 

Finding Out What Devices are Accessible 

Now that you have the Filer prompt on the screen, press ( V ) . This initiates the Volumes 
command and the screen now displays the volumes or I/O units associated with the Pascal 
System. Here is a typical display (yours may vary slightly): 



Moluines on-line: 


1 


CONSOLE: 


2 


SYSTERM: 


3 * 


MYVOL: 


a # 


ACCESS: 


5 * 


SRM-WORK: 


G 


PRINTER: 


as * 


SYSTEM04: 


Prefix is - MYVOL. 



For each volume, the display shows the logical unit number and the associated volume which 
are currently on-line. Volumes #5 and #45 are SRM volumes which you may or may not have. 
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The "#" beside units 3, 4 and 5 indicates that these are blocked devices. These are used for mass 
storage. The "*" beside unit 45 indicates that this is the system volume; also a blocked device. 
The system volume is used by the system during certain operations and should be left on-line at 
all time if possible. "Prefix is" indicates which is the default volume. The default volume is 
assumed when no volume identifier is given. The default volume can be changed using the Filer's 
Prefix command and the Main Command Level's What command. 

The Default and System Volumes 

At power-up, the system generally designates the highest performance mass storage device as the 
"system volume" because it needs a volume to work with occasionally. The system volume is 
denoted by an asterisk (*) in the Volumes command display and remains fixed unless the New 
system volume command or the What command is used at the Main Command Level. 

The Prefix command, because it defines the default volume, lets you specify a particular volume 
where the Pascal System will look for files when you haven't given a volume name or logical unit 
number. This is handy in the Filer as well as in other subsystems such as the Compiler or Editor. 

The default volume can be in dicate d with the colon (: ) character. For example, to list the directory 
of the default volume, press ( L ) (for the List directory command) and answer the prompt by 
typing ":". The Filer then displays the directory of the current default volume. 

Changing the Default Volume 

You can use the Volumes command (from the Main Command Level) to see what volume is the 
current default volume. It is listed under the heading Pre f ix in the Volumes display. You can 
also see what the current default volume is by pressing ( P ) for the Prefix command. The 
screen displays: 



Prefix to what director-/ 



Respo nd by pressing (Return) or (ENTER) . The screen now displays the current default volume. Now 
press ( P ) again and in response to the prompt, type MO JO : . The screen now displays: 



Prefix is MOJO: 



Now, whenever you want to specify a file or group of files on the MOJO: volume, you can just 
type the file name(s) and the Filer will assume that the file or files specified are on the volume 
MOJO:. 

It is possible to set the default prefix to a flexible disc drive, regardless of the volume inside. This is 
done by typing: 



»3: (Return) or (ENTER) 
while the drive door is open. 
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The prefix command is used to set up a working directory on a Shared Resource Management 
system as well. If you had an SRM file named: 

*5 : USERS/ JOE/ PRO JECT1/ PROGRAMS/ FILE 

Initiate the Prefix command as usual and specify: 
#5: /USERS/ JOE/ PROJECT 1/ PROGRAMS 

This sets the SRM volume as the default volume and USERS/JOE/PROJECT1/PROGRAMS as 
the working directory on the SRM. If the previous working directory had been PROJECT1, then 
only PROGRAMS need be typed. Now you can specify the file with: 

FILE 

If you were to use the Prefix command again to set the default prefix to another volume (not on 
the same unit), the working directory and volume name for the unit remain PROGRAMS. You 
need only specify either of the following to get the same file. 

#5:FILE 

or 

PR0GRAMS:FILE 

It is possible to change the working directory on an SRM u nit without changing the default 
volume. Use the Filer's Unit directory command. Press ( U ) and then give the directory name 
that you wish to become the working directory. If the new directory is in the existing working 
directory, just type the new directory name. If it is not, type the whole directory path as shown 
above in the Prefix example. 



Note 

Do not use the Prefix command on unit #45. This is the system 
volume and should not be altered. 



The System Volume 

The system volume can also be specified in a shorthand form using the "*" character. Suppose 
you want to specify the file named LIBRARY on the volume SYSVOL:. Assuming that SYSVOL: 
is the system volume and is currently in the disc drive associated with unit #3, you can specify a 
file on that volume by entering any one of the following three methods: 

SYSVOL: LIBRARY 

or 

#3:LIBRARY 

or 

♦LIBRARY 
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Of course you can make the specification even shorter by typing something like: 
* = ARY 

However, if you are doing a critical operation, be sure that there are no other files on the same 
volume which fit that file specification or use the ? wildcard instead. If a file named GARY existed 
on SYSVOL:, the operation would also be performed on it. Once again, use wildcards judi- 
ciously. 



Listing a Directory 

To find out what files are on the disc called ACCESS:, press [ L ) to initiate the List Directory 
command. The Filer prompts you to specify the volume whose directory is to be listed: 

List what director-/ ? 



Respond by typing ACCESS: and pressing ( Return ) or (ENTER) . Notice that the colon ( : ) is part of the 
volume specification. The screen now displays the directory (catalog) for ACCESS:. It looks 
similar to this display: 



ACCESS: 

created 8-0ct-B: 

Storage order 



Directory t y p e = LIF level 1 
3.47,54 block size =256 



« . . f i 1 e name ... . 


# blKs 


* bytes 


last chns 


FILER 


218 


55808 


8-0ct-82 


EDITOR 


228 


583G8 


8-0ct-82 


LIBRARIAN 


202 


51712 


8-0ct-82 


MED I A IN IT. CODE 


132 


33792 


8-0ct-82 


TAPEBKUP.CODE 


54 


13824 


8-0ct-82 



FILES shown =5 allocated =5 unallocated =11 

BLOCKS (258 bytes) used =834 unused =2 18 largest space=218 



The name of the volume is displayed in the upper left-hand corner of the listing. To the right, 
the directory type is displayed. Pascal discs have Level 1 directories. Level 1 directories contain 
the date the directory was created and the size of the volume. Level directories do not. Your 
directory listing should display the date the directory was created and the date it was changed as 
system volume, the size of the storage blocks, and whether the listing is in storage order or 
alphabetical order. The size of blocks on LIF volumes is 256 bytes (1 sector). The size of blocks 
on WS1.0 volumes is 512 bytes. The Shared Resource Management system does its accounting 
in 1-byte units. To have directories listed in alphabetical order, include [*] after the directory 
name. For example: 

LIFDIR: [*] 



The column entries for each file include: file name, number of blocks used for storage, the file 
size in bytes, and the date the file was created or changed. 
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The last two lines display additional directory information including how many more entries can 
fit in the directory. The size of a directory is specified when the disc is initialized. 

Getting a More Detailed Listing 



To get a more detailed listing of the directory on a disc, press ( E ) (for the Extended 
Directory command) and you will be prompted for a volume name as before. Respond by 
typing: 



ACCESS: ( Return ) or (ENTER) 
Your screen now displays: 



ACCESS3: Directory type = LIF level 1 

created 8-0ct-82 3.47.54 block size=25G 
StoraSe order 



file name . 



* blKs 



* bytes 



start b 1 k ....last change. . .extension! 



type t-code ..directory info. 



.create date... extensionZ 



218 55808 
Code -5582 

228 5B3G8 
Code -5582 

202 51712 
Code -5582 

132 33792 
Code -5582 

54 13824 
Code -5582 
218 

FILES shown=5 allocated = 5 unal 1 ocat ed = 1 1 
BLOCKS (258 bytes) used=834 unused=218 largest space=218 



FILER 

EDITOR 

LIBRARIAN 

MED I A I NIT. CODE 

TAPEBKUP.CODE 

< UNUSED > 



4 B-Oct-82 3.48. B 

222 B-0ct-B2 3.48.18 

450 8-0ct-B2 3.48.35 

652 8-0ct-82 3.48.44 

784 B-0ct-82 3.48.48 
83B 



The Extended directory listing contains all the same information as the List directory listing with 
additional information. It also contains the number of the block where the file starts, the type as 
recognized by the file system, the type-code used by the directory system, SRM access informa- 
tion and two extension fields. 

The "directory info" column shows the public access rights and the current file status for SRM 
files. (Because the listing above is not from an SRM volume, the column is empty.) 
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If one of the letters from the table below is missing, then the public access right associated with 
that letter has been removed. 



Letter 


Access Right 


M 


Manager 


R 


Read 


W 


Write 


S 


Search 


P 


Purgelink 


C 


Createlink 



Public access rights on a file are established at one of two times. If a file is created by a program, 
the public access rights can be established when the file is opened. To do this, use the optional 
third parameter on the command used to open the file. The commands used to open files are 
Reset, Rewrite, Open and Append. The optional third parameter is explained in more detail in the 
File System chapter and in the HP Pascal Language Reference. 

If a file already exists, the Filer's Access command can be used to establish or, if the Manager 
right has not been removed, change the public access rights. 

The possible "current file status" are listed below and explained in the "File System" chapter. 

CLOSED 
SHARED 
EXCLUSIVE 
CORRUPT 

The two extension fields are for LIF directories only. The other directories display a " — 1". For 
most LIF file types, extensionl contains a "0". For system files, it contains the start execution 
address. For data files, it contains the logical end-of-file. Extension2 contains the volume 
number in cases of multi-volume files. The Pascal system cannot create or read multi-volume 
files; the LIF DAM merely recognizes them. For single volume files, it contains a "1". 

The above examples are the most common uses of the directory listing commands, but there 
are two other useful ways of using the command. One is to use a "wildcard" to specify a subset 
of files that you want listed. The other way is to send the listing to the printer or to a file instead 
of letting the listing default to the screen. Both methods are comb ined i n the example below 
and are covered in detail in the "Filer Commands" section. Press ( E ) again (to initiate the 
Extended Directory command) and answer the prompt for a volume specification as shown in 
the display: 



List_ext what directory? ACCESS : = . CODE PRINTER : (Return) or (ENTER) 



The ACCESS: volume should be on-line. Your specification tells the Filer you want a listing of 
all the files on the ACCESS: disc whose name ends in ".CODE". The " = " acts as a substitute 
for all combinations of characters in a file name. The "," separates the source specification from 
the destination specification. The listing should only display the files whose names end with 
".CODE". The EDITOR, FILER and LIBRARIAN are not listed because their names don't end 
in ".CODE". 
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A Few Words About Wildcards 

Wildcards are powerful tools for executing Filer commands on related files. There are three 
wildcard characters. 



A wildcard is a substitute for an arbitrary portion of a file name. For example, if you wanted to 
list all the .CODE files on the EXAMP: volume, you could specify: 

EXAMP:=.CODE 

The " = " stands for any combination of characters. If the file name ended with ".CODE", that 
file would etppear in the listing. If you wanted to remove some of the .TEXT files on the EXAMP: 
volume, you could specify: 

EXAMP:?. TEXT 

The "?" also stands for any combination of characters. However, the Filer will ask you, one at a 
time, if you want to remove each file that fits the specification. The "?" wildcard lets you verify 
operations before actually performing them. Unless you are absolutely certain about the effects 
of a command using the equals sign wildcard ( = ), its best to use the question mark — by far the 
safer of the two. 

The "$" character is a valid wildcard for destination file specifications. It indicates that the file is 
to retain its original name. If "$" is used with other characters, it is used as part of the name. 

Wildcards act as replacement strings in file names. Part of a file name can be given before or 
after the wildcard or both before and after. For example, two files named WILD. TEXT and 
WILD. CODE on the default volume could be specified by: 

WILD? or WILD= or =LD.= or ?ILD = 
Partial file names must be given in the order in which they appear in the file name. 

Translating Text Files 

The Pascal system supports several different types of "text" files. These files are usually created 
by the Editor and can be programs, documents, or data. When the file is stored on a disc, the 
internal representation (format) of the file is determined by the suffix appended to the file 
specifier. The different formats have different information in the file header and can have 
different end-of-line schemes. The Translate command can be used to convert from file type to 
another. The various file formats recognized by the Pascal system are TEXT, ASCII, and DATA. 
No suffix indicates a DATA file, a .TEXT suffix indicates a TEXT file and a .ASC suffix indicates 
an ASCII file. 



To use the Translate command, press ( T ] and see the prompt: 



Translate what file 



1 



112 The Filer 



Respond with the name of your input file 
MYVOL:MYFILE.TEXT 

The Filer will then prompt: 



Translate to what ? 



Respond with the name of your output file 
MYUOL:NEWFILE.ASC 

The Filer will create an output file of a type corresponding to the suffix on the output file name 
(ASC in the example) and will read the text data from the input file, reformat the data to match 
the output file type, and write the data to the output file. This process may seem slow, but 
remember that the text is being reformatted. 

Sending File Listings to the Printer and Screen 

The Translate command is used to send files to the printer or to the screen. Logically, the printer 
and screen are just files of a different format. 

Before using the Translate command, remove the volume ACCESS: and replace it with the 
volume DOC: (supplied with this manual set). Now use the Extended Direct ory co mm and to 
display the contents of the DOC: volume. Press ( E ) , type in DOC: and press (Return) or (ENTER) . 
Your screen should display all the files on the documentation disc. 

Press the space bar: this clears the screen of everything except the Filer prompt. Now press 
( T ) to initiate the Translate command. The screen prompts you with: 



Translate what file ? 



Respond with DOC : BINDOC . TEXT and press ( Return ) or (ENTER) . The screen now prompts: 



Translate what file ? DDC : BINDOC , TEXT 
Translate to what ? 
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Your first response includes both a volume specification and a fil e nam e an d com pletely identifies 
the file you want to transfer. Now type PRINTER: and press ( Return ) or (ENTER) . The text file is 
translated to the printer as shown: 

BEGIN -CBinery -search} 
done : = FALSE 5 btm:=0i top:=2G! {initialize} 
FOR 1oop: = 1 TO top DO al phaC 1 oop] : =CHR ( 1 oop+Ga ) 5 
WRITELN ( 'Type uppercase character for a Key')! 
READ(Kev); WRITELN; 
WHILE NOT done DO 

BEGIN {This is the actual binerv search} 

mid:= ROUND((top + btm>/2)5 

IF key = alpha[mid3 THEN done:= TRUE 
ELSE IF Key < alphaCmid] THEN top:=mid 
ELSE btm: =mid 5 
IF top=btm THEN BEGIN 

done : = TRUE 5 mid: = -15 
END! 
END! 
IF mid > THEN 

WRITELN('Kev -'tkevt'- is in position '»mid:2) 
ELSE WRITELN('Key - '»key»' - was not found')! 
END. 

The Filer shows you what operation it has just performed by displaying: 



DOCsBINDOC.TEKT ==> PRINTER: 

Since the operation is complete, the Filer again displays its prompt. Note that only files of type 
TEXT, ASCII or DATA should be sent to the printer. You can also Translate these files to the 
screen by using CONSOLE: in the destination specification instead of "PRINTER:". Th e file i s 
displayed one screen at a time. Press the spacebar to move to the next screen; press [ SHIFT ) - 
( Select ) ( ( SHIFT ) - ( EXECUTE ) ) to abort the operation. 

If you are not sure if the file in question is a text file, use the Extended Directory command and look at 
the column in the display where the file types are shown. 

Copying Entire Volumes: Backup Copies 

The backup process described here is suitable for volume-to-volume copies if both volumes are 
the same size. For different size volumes, see Filecopy in the "Filer Commands" section. 

Note 

Using Filecopy to copy an entire volume will result in the loss of disc 
space if the source volume is smaller than the destination volume. To 
copy a volume to a larger one, Filecopy individual files. 
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You should still be at the Main Command Level and now have a blank initialized disc. We will 
use it for a volume-to-volume filecopy. Volume-to-volume filecopies do not require that a 
directory be present on the destination disc. 



Insert ACCESS: in the disc drive. Press ( F ) and the Filer gets loaded and displays its prompt: 

r ' * 

Filer: Change Get Ldir New Quit Remove Saue Translate Uols What Access Udir ? 



Press ( F ) for the Filecopy command and the screen shows: 



Filecopy what file ? 

Now type ACCESS: and press ( Return ) or (ENTER) . The screen displays: 

, 



Filecopy what file ? ACCESS: 
Filecopy to what ? 



You can specify a volume by specifying the logical unit numb er associated with the physical disc 
drive that it is in. Do this by typing #3: and pressing ( Return ) or (ENTER) . The Filer knows that 
ACCESS: is currently in the drive associated with unit #3 and figures that you want to transfer 
that volume to a different volume that will be inserted in the same drive. The Filer then reads as 
much of ACCESS: as it can into read/write memory and the screen displays: 



Please mount DESTINATION in unit #3 
' C ' continues* < s h - e x c > aborts 



Now remove ACCESS:, replace it with the blank initialized disc, and press ( C ) . Since no 
directory is on the initialized volume, the Filer simply copies the ACCESS: information that it 
read into memory onto the new disc. If there had been a directory named TESTER: on the 
destination volume, the Filer would have prompted: 



Destroy directory of TESTER; 



(Y/N) 



This precaution makes sure the information on the disc does not get destroyed if you change 
your mind or inserted the wrong disc. Answering with ( N ) for "No" aborts the Filecopy 
operation and the Filer prompt returns. Answering with a ( Y ) for Yes lets the Filecopy take 
place and the contents of ACCESS: are written to the new disc. This operation destroys the 
directory (and, effectively, all information) that was previously on the destination disc. 

In case your machine does not contain enough memory to read in the entire volume ACCESS:, 
the Filer prompts you to swap the source and destination discs as many times as necessary to 
complete the Filecopy operation. When the operation is complete the Filer prompt reappears. 
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If you have more than one disc drive you can accomplish the same task by specifying both the 
source and destination volumes with either a volume name (if it has one) or by the unit number 
associated with the drive it is in. This second method of doing volume-to-volume transfers is 
quicker — especially if the amount of memory in your machine is relatively small. 

Note 

Having two volumes with the same name on-line at one time is not 
advised. The Filer looks for volumes according to their volume names 
and may not be able to distinguish one from the other. Thus, the Filer 
may perform an action on one volume when you wanted the opera- 
tion to affect the other volume. The Filer warns you whenever it 
detects that this condition exists. If you get a warning, either remove 
one of the volumes or use the Filer's Change command to change the 
name of one of the volumes. 

Creating a Directory 

In general, the Filer only works with volumes that already have directories. There are a few 
exceptions to this rule, such as volume-to-volume transfers where the directory from the source 
volume is copied onto the destination volume. Other exceptions are mentioned as they arise. The 
Filer's Zero command creates an empty directory on a new disc that has been initialized using the 
MEDIAINIT program, previously used discs, or on any other compatible type of mass storage 
device such as a hard disc or a volume stored in read/write memory. The Zero command, 
however, is not used to create directories on the Shared Resource Manager. This is done with the 
Filer's Make command because making an SRM directory really involves making a file of type 
"directory". 

Your screen should now display the Filer prompt. Remove the current volume from the disc drive 
associated with unit number 3 and replace it with the second disc that you initialized. Now press 
( Z ) to initiate the Zero command. The screen displays: 



lero directory (NOT valid for SRM type units) Zero what volume? 



The request is for a volume specification. Answer with «3 : and press ( Return ) or (ENTER) . The Filer 
now prompts: 



Destroy U3: ? (Y/N) 



This question is just a safety precaution so that you won't destroy a volume full of information 
by accident. "V3" is the name given to the directory by MEDIAINIT (if created on unit #3). 
Press ( Y ~) for yes. The next prompt is: 

\ 

I Number of directory entries (8)? I 
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This is asking for the maximum number of files that will be listed in the directory. The number in 
the parentheses is the default that will be used if no value is given and is derived from the 
number in the existing directory. In most cases, 80 directory entries is a good choice. 

The next prompt is: 



Number of bytes (270336) 



This is asking for the total size of the disc to be handled by the directory (the logical size of the 
volume). The number in the parentheses is derived from t he num be r in th e existing directory (if 
any) or from the unit table entry for that given unit. Press (Return) or (ENTER) to accept the default 
size for your disc. 

The system now prompts you for a volume name. Volumes and volume name syntax for the 
different directory types are described in the File System chapter. Briefly, LIF directory names 
must be six characters or less; upper and lower case characters being distinct. WS1.0 directory 
names must be 7 characters or less and are always uppercased before being written in the 
directory. The Filer then confirms that the volume name is the one you wanted. The screen now 
appears: 



Zero directory (NOT valid for SRM type units) 

Zero what volume ? «3 

Destroy ACCESS: ? (Y/N) Y 

Number or directory entries (8) ? 80 

Number of bytes (270336) ? 

New directory name? NEWONE 

NEWONE: correct ? (Y/N) 



When you press ( Y ) to confirm the new volume name the Filer informs you that the volume 
with that name has been zeroed and the Filer's prompt appears. Your new volume is now ready 
for use. 

Copying Files from Volume to Volume 

The Filecopy command allows you to copy files from one volume to another or even to a different 
place on the same volume. The volumes can be separate discs, SRM directories or, in the case of a 
hard disc, multiple volumes on the same physical device. 

Remove the current volume from drive #3 and insert the DOC: volume supplied with this 
document set. To copy a file from one volume to another, press ( F ) for Filecopy and respond 
to the prompt for a file specification with: 



DOC: STREAM. TEXT 
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When the Filer prompts you for a destination, type in the specification shown below and press 
(Return) or (ENTER) . 



Filecopy what file ? DOC : STREAM . TEXT 
Filecopy to what ? *3:$ 



What happens here is similar to copying a volume from one disc to another using a single drive. 
The Filer reads the contents of DOC:STREAM.TEXT into memory and then displays the 
message: 



Please mount DESTINATION in unit »3 
'C' continues t <sh-exc> aborts 



Take another disc and insert it in drive #3. Now that you have your new disc in drive #3, press 
( C ) to continue. The Filer writes the contents of the file that it temporarily stored in memory 
to the disc you just inserted and confirms that the Filecopy has taken place. 

If you give a unit number (as above) or a different volume name which is not on-line, you must 
swap discs to complete the copy. 

The wildcard ($) is a feature to avoid repetitious typing and tells the Filer to give the destination 
file the same name as the original file — STREAM. TEXT. 

When copying a file to a different volume, always include either a file name or the * character 
when you specify the destination. If you specify the name of a mass storage volume without a 
file name, the Filer prompts: 



Destroy directory of SYSYOL: ? 



1 



Although the volume name may be different, if you answer with a ( Y ) , the Filer transfers the 
specified file to the destination volume, destroying the directory in the process, and rendering 
all previous information on that volume useless. 

The next example demonstrates how to cop y multiple files from one volume to another using 
the ? character as a wildcard. Press ( F ) once again and respond to both the prompts as 
shown: 



Filecopy what file ? DOC : M0D7TEXT 
Filecopy to what ? MKW0RK:$ 
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This tells the Filer to copy all the files on the DOC: volume that begin with the characters "MOD" 
and end with the characters "TEXT" to the volume MKWORK:, giving each the same name it had 
on the DOC: disc. Before the Filer actually copies any files, however, it will verify with you that you 
actually want to copy each file that fits the specification. Respond to each prompt with a ( Y ) for 
"Yes." As you answer each prompt affirmatively, the Filer copies the corresponding file to the 
destination (MKWORK:) volume. If you have a single-drive system, the Filer will prompt you to 
swap the discs as in the previous example. 

It is worth mentioning that, although specifying a unit number is less typing than specifying a 
volume name, when you specify a unit number the Filer initially accesses the volume (disc) 
currently in the drive without regard to whether or not it was the one you intended. After the 
first access of a volume, the Filer associates a supplied unit number with the name of the 
volume found in that device. However, if you specify a volume name, the Filer only performs 
the command on that volume. If the volume you specified is not on-line the Filer will tell you so. 
Specifying the volume name is a good habit if you are doing a lot of disc "swapping"; this will 
insure that the Filer does not operate on a disc other than the one you intended to use. 

In cases where the destination volume already contains a file with the same name as the file 
being copied, this prompt is displayed: 



ANYYOLiXFILE 

exists ... Remove* Overwrite* Neither ? (R/O/N) 

You have the options: 

• Remove — remove the original file first, then write the new file in the largest space 
available. 

• Overwrite — replace the contents of the old file with the new information. The Overwrite 
option cannot be used to change the type of a file on SRM. Attempting to do so will result 
in the file contents being inconsistent with the file type. 

• Neither — cancel the operation. 

The Overwrite option allows you to put a file in the same starting location as the original. This is 
important to SRM users when duplicate links exist to a file. All links and passwords to the file are 
accurate when a file is updated because it is put in the same logical location. If you chose the 
Remove option, the original file would not actually be removed; only your link to it is removed. 
The other user's directories are still linked to the original file. 



Note 

Be careful when using the Overwrite option on an SRM system. If the 
file specifier suffix (.TEXT, .ASC, or none) is not the same as the 
original file suffix, the contents of the file may become inaccessable. 
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Note 

The Pascal Filer can also copy BDAT (BASIC Data: file type -5791) 
files produced by the HP BASIC workstation system. However, there 
are some side effects that occur when copying BDAT files from LIF to 
SRM directories, and vice versa. See the description of the Filecopy 
command in the "Filer Commands" section near the end of this 
chapter. 

Renaming Files and Volumes 

The Filer's Change command allows you to rename files and volumes. (The one exception is that 
the root directory of the Shared Resource Manager cannot be renamed. ) This command requires 
two specifications: the original name and the new name (the first name may include volume 
specification and pathname and passwords for SRM but the second name cannot). Assuming 
that the volume MKWORK: is still on-line, press ( C ) for Change and respond to the prompt as 
shown: 



Change what file ? MKWORK : »MOJO : 



1 



The volume name is now "MOJO:". To change the file STREAM.TEXT on the MOJO: volume to 
RIVER . TE XT yo u can either type out both names (separated by either a comma or a press of the 
[Return] or (ENTER) key) or use a wildcard as shown below: 



Change what file ? STREAM= 
Change to what ? RIUER= 



The Filer changes the file name as described. The wildcard was used as a substitute for the .TEXT 
part of both names. The only restriction on using wildcards with this command is that if you use a 
wildcard in one of the specifications, you must use it in the other. Because the strings or subsets 
represented by the wildcard are not always obvious, discretion is advised when using wildcards 
with the Change command. 

When changing the name of a file of type TEXT or CODE, remember that parts of the Pascal 
System attempt to append the suffixes ".TEXT" or ".CODE" to the file you specify. You can get 
around this by specifying a file and adding a period (. ) to the file name. This tells the system not to 
append the suffixes to the file name for which it searches. 



Note 

Excluding the Get command, the Filer makes no assumptions about 
sufixes and will treat a trailing period as part of the file name. 
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Removing Files 

The Remove command is provided to delete files from a directory of a block structured volume. 
Suppose you have a volume on-lin e named NEWSTUF: containing the file POLYNOM.TEXT 
that you wish to delete. Press [ R ) to initiate the Remove command and respond to the prompt 
as shown: 



Remove what file ? NEWSTUF : P0LYN0M . TEXT 



Then press ( Return ) or (ENTER) . The Filer removes the specified file from the volume and reports: 



NEWSTUF: POLYNOM.TEXT removed 

The Filer prompt reappears as the message is displayed. As in many of the Filer's commands, the 
prompt requests a file specification. Wildcards can be used with the Remove command but 
should be used carefully. The question mark (?) wildcard provides an easy method for removing 
a TEXT and CODE file of the same name. It also lets you verify the operation (a good practice 
when purging files). 

Suppose the same volume NEWSTUF: contains two files you wish to remove called IOTEST 
. TEXT and IOTEST. CODE. To remove these files answer the "Remove what file ?" promptwith: 

NEWSTUF: IOTEST? 

and press [Return] or (ENTER) . The Filer responds with: 
Remove IOTEST, TEXT ? (Y/N) 

Reply with ( Y ] (for Yes) to remove the file. Reply with ( N ) (for No) if you change your 
mind. Either reply results in the next prompt: 

Remove IOTEST. TEXT ? (Y/N) Y 
Remove IOTEST. CODE ? (Y/N) 

Reply as before and the Filer responds with: 

Remove IOTEST. TEXT ? (Y/N) Y 
Remove IOTEST. CODE ? (Y/N) Y 
Proceed with remove ? (Y/N) 

This gives you one more chance to change your mind about the op eration. T he file s are not 
actually removed from the volume's directory until you press ( Y J . Pressing ( N ) has the 
same effect as if you had never initiated the command (i.e. , the directory remains unchanged and 
your files remain intact). 
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If you want to remove all of the files on a volume (for discs only; not SRM), the quickest way to do 
so is to execute the Zero command. This command wipes out the directory of a volume so that the 
volume may be re-used. See the description of the Zero command earlier in this section or in the 
"Filer Commands" section. 

Leaving the Filer 



Exit the Filer by pressing ( Q ) for Quit from the Filer prompt. You will imm ediately b e retu rned 
to the Main Command Level. The Filer can also be exited with the ( STOP ) key. The ( STOP ) key 
waits for any current disc I/O to complete before it actually executes. This key can be used at any 
time — even while executing a Filer command. Howeve r this p ractice is not recommended since 
some commands may cause damage to your files if ( STOP ) is pressed while they are being 
accessed. 

The System Workfile (A Convenient Scratchpad) 

The Pascal System features a workfile which can be used in the Filer, Editor, Compiler and 
Assembler. Each subsystem that uses the workfile documents its use. 

Think of the workfile as being analogous to a default volume. In some of the subsystems, you are 
not prompted for a file specification when entering the subsystem if a workfile of the appropriate 
type exists. For example, if the text version of a workfile exists when entering the Editor, the 
Editor never prompts you for a name of the text file to edit but reads in the workfile instead. As a 
matter of fact, before you can edit any other file, you will need to use the Filer's New command 
(preceeded by the Save command if you want to retain the file) to release the workfile. In the 
same manner, invoking the Pascal Compiler when the text version of a workfile exists results in 
that file automatically being compiled. 

If the Filer's Get command is used, the workfile is the TEXT/ASCII/DATA and/or CODE file 
specified in the command. 

The Filer has four commands (Get, New, Save and What) which operate directly on the workfile. 
These are covered in the next section. 
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Filer Commands 

This section contains a brief overview and summary of the Filer commands and a complete 
alphabetized description of the syntax and semantics of all the Pascal Filer commands and 
options. 



Filer Command Summary 



Volume Related Commands 

Bad sectors - Scans a volume and searches for 
unreliable (bad) storage areas. 

Extended Directory - Lists directory information 
about a specified volume or set of files. 

Krunch - Consolidates all unused space on a 
volume in a single area by packing the existing 
files together. (Not valid for SRM) 

List Directory - Lists directory information about 
a specified volume or set of files. 

Prefix - Specifies a new default volume. 

Volumes - Lists the volumes currently on line. 

Udir - Sets the default unit directory. (SRM only) 

Zero - Creates an empty directory on the speci- 
fied volume. (Not valid for SRM) 

Exit Commands 

Quit - Provides an orderly exit from the filer. 

STOP - Pressing the ( STOP ] key unconditional- 
ly exits the Filer Subsystem. The current I/O 
operation is completed before exiting. 



File Related Commands 

Access - Change the access rights (passwords) on 
a file or directory. (SRM only) 

Change - Change the name of a file, set of files, or 
volume. 

Duplicate link - Duplicates links to a file or set of 
files. (SRM only) 

Filecopy - Copies a file, set of files, or a volume to 
a specified destination. 

Make - Create a directory (SRM) or a file on a 
volume. 

Remove - Remove a directory entry or a set of 
directory entries. 

Translate - Translates text files of types TEXT, 
ASCII, and DATA to other text file representa- 
tions or to unblocked volumes. 

Workfile Related Commands 

Get - Specifies a file as the workfile. 

New - Specifies that no file is the current workfile. 

Save - Saves the current workfile(s) with the spe- 
cified name. 

What - Lists the name and current state (saved or 
not saved) of the workfile(s). 
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Command Syntax and Semantics 

The Filer commands are presented in alphabetical order. Each command's explanation includes: 
the command's name, a brief functional description, a diagram showing its legal syntax (See 
Chapter 1 ) , the command's prompt (if any) and text which discusses using the command. Each 
command's options are also covered and some have examples to show the proper use of these 
options. 

Several of the syntax diagrams on the following pages reference the the "volume only specifier" 
and the "complete file specifier" below. The "volume only specifier" is the syntax for commands 
that operate on volumes. The "complete file specifier" is the syntax for commands that operate 
on files. Volume only specifiers don't need the ":" except when a literal volume name is given. 
Then the name must end with a ":" to distinguish it from a file name. If no volume specifier is 
given, the default volume is assumed. 

Alphabetical List 
of Filer Commands 

Access 

Bad sectors 

Change 

Duplicate 

Extended directory 

Filecopy 

Get 

Krunch 

List directory 

Make 

New 

Prefix 

Quit 

Remove 

Save 

Translate 

Unit directory 

Volumes 

What 

Zero 
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File Specification 



— *\*J *• ^"*\<) — ■" password — *\>J 



»fit\ J unlt 
^3/ ~numbe 



volume 
name 



^ 



^ 



<z> 



directory 
name 



file 
name 



^-*\<) — ** password — *\ > J 

• — *G) — J 



-0- 



Item 




Description/Default 




Range 
Restrictions 


unit number 


integer; 
table 


corresponding 


to an 


entry in 


the unit 


1 thru 50 


volume name 


literal 










any legal volume name 


password 


literal 










any legal password 


directory name 


literal 










any legal SRM directory 
name 


file name 


literal 










any legal file name 


number of blocks 


integer 










any legal number of 
blocks 



See Chapter 2 for legal names and values. 
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Volume Specification 



-0 

+fit\ j unit 

\*V/ numbe 



•l 1 !-^-^ 



volume 
name 



Item 


Description/Default 


Range 
Restrictions 


unit number 
volume name 


integer; corresponding to an entry in the unit 
table 

literal 


1 thru 50 
any legal volume name 
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Access 

The Access command allows you to change public access rights on your files (SRM only). 



V ^ 1 — — 'J "specification 



-*(m>- 



<gd}^ 



password 



KD-l- 



O 



attr ibute 



password 




U(m> 



Q 



(Return) or 1 EHTEB) 



>H 



Item 




Description/Default 


Range 
Restrictions 


file specification 


literal 






a legal SRM file 
specification 


attribute 


literal 






MANAGER READ 
WRITE SEARCH 

PURGELINK 
CREATELINKALL 


password 


literal 






any legal password (See 
Chapter 2 for details) 



Semantics 

The Access prompt: 

Access rights for what file ? 

Type the file specification. If the file already has a Manager password, then you must include the 
password in the file specification. Access rights cannot be changed on open files or open working 
directories. 

The next prompt: 

Access: List* M a K e > Remove* Attributes t Quit ? 

These are the possibilities. You can list the attribute passwords, make new ones or remove 
passwords. The Attributes option just lists the possible attributes for your help. Quit returns you to 
the Filer prompt. 
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To make new passwords, press [ M ) . You see this prompt: 
M a K e p a s s w o r d : a 1 1 r i b u t e ? 

Type the password (up to 16 characters), then a colon (:) and the attribute list (attributes 
separated by commas). Different passwords may be associated with each attribute or one with 
ALL. If you type a password that already exists, you are asked: 

PASSWORD already exists. ..replace it ? (Y/N) 
Note that passwords should not contain the characters: ">", ":", ",". 



To remove passwords, press ( R ) . You see the prompt: 

R e in o v e password ? 

Type only the password and all attributes associated with it are cleared. 

The Attributes option list: 

MANAGER 

READ 

WRITE 

SEARCH 

PURGELINK 

CREATELINK 

ALL 
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Bad sector 

The Bad sector command scans a mass storage medium for errors. 



C^ ^Bpecm^tionhK C^"Cai) ) ~H 



Item 


Description/Default 


Range 
Restrictions 


volume specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Bad sector prompt: 

Bad sector scan of what directory ? 

The Bad sector command allows you to check a mass storage medium to find out if each block 
(sector) is readable. A flexable disc may become unreliable after damage or excessive wear. 



Press ( B ) to initiate the command and answer the prompt with a volume only specifier. The 
Filer then displays a message indicating that it is scanning the volume from block to the end of 
the volume. The Filer does a read operation on each sector and does a CRC error check on the 
results. If the CRC results are normal, that sector is considered to be good; if not, the Filer lists the 
sector number. 

If you find a bad sector in a file, you may wish to use the Filer to change the file type (suffix) to 
. BAD. (You did make a back-up copy didn't you?) The BAD file will not be moved in a Krunch 
operation. A large number of bad sectors indicates a worn-out medium. The medium should only 
be used if you are willing to risk losing information on that volume. 
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Change 



The Change command lets you rename files, directories and volumes. 



(m> 



file 
spec i f icat ion 



new file 
name 



*/ ( RHurn ) or [ ENTER ) J ►■( 



volume 
specification 



^— */ | RHurn ) or [ ENTER] J ■* 

— a— 



new volume /^""^ 4 

name ^\l*s 



^-+\ (Return) or HhTER] J * 



Item 




Description/Default 


Range 
Restrictions 


file specification 


literal 






(See the beginning of 
this section) 


volume specification 


literal 






(See the beginning of 
this section) 


new file name 


literal 






any valid file name 


new volume name 


literal 






(See the beginning of 
this section) 



Semantics 

The Change prompt: 
Change what file? 

The Change command requires two specifications: the original volume or file specification and 
the new one. The two specifications can be separated by either a comma or a carriage return. If 
you are changing the name of a volume, any legal volume ID can be used for both specifications. 

To change the name of a file, use any legal volume ID in the first specification and only the new 
file name in the second specification. The Filer is intelligent enough to know that the file whose 
name you are changing resides on the volume identified in the first specification. After the Filer 
has finished changing the name and updating the directory it reports the name changes it has 
made. 

Because many of the Pascal subsystems append the string . TEXT or . CODE to a file name given 
in response to a prompt, it is a good idea to retain these parts of a file name when making a 
change. 

Wildcards (the = and ? characters) may be used in the Change command. If a wildcard is used in 
the first specification, it must also be used in the second one. The subset string that is replaced by 
the wildcard in the second specification (the new name) is the same as the string it stands for in the 
first specification. 



130 The Filer 



Suppose you have a volume named BUGS : with the following files: 



WHAT I SIT. TEXT 
WHOISIT.TEXT 
WHY I SIT. TEXT 

Specifying BUGS:WH=TEXT» F0 = FA in response to the Change prompt results in the following 
messages being reported by the Filer: 

BUGS:WHATISIT,TEXT changed to FOATISIT.FA 
BUGS:WHOISIT.TEXT changed to F00ISIT.FA 
BUGS: WHY IS IT. TEXT changed to FOYISIT.FA 

Here is another example using the original files shown above on the BUGS : volume. Specifying 
BUGS :WH= .TEXT , = results in: 

BUGS:WHATISIT.TEXT changed to ATISIT 
BUGS:WHOISIT.TEXT changed to OISIT 
BUGS: WHY I SIT. TEXT changed to YISIT 

You may wish to create some empty files using the Make command and experiment with them 
before using wildcards extensively. Until you get used to them, the effects of wildcards are not 
always obvious. 



Note 

Using the Change command to "change" a file name to the same 
name results in the file being removed. 



Note 

The Change command does not change the file type. 
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Duplicate_link 



The Duplicate Jink command establishes a new pointer to a file (SRM only). 



kiv 



Q r H SPe ci f fYc e atT3 -* ( ^° r « ) -h 



^-»"( Beam; or [ENTER) J ^ 



Item 



file specification 



Description/Default 



literal 



Range 
Restrictions 



(See the beginning of 
this section) 



Semantics 

The Duplicate link prompt: 

Duplicate linK (ualid only for SRM type units) 
Duplicate or Move ? (D/M) 

Do you want the original pointe r to th e file removed after the duplicate link is established? If you 
do, type ( M ) — if not, type ( D ) . 

The next prompt: 

Dup.link what file ? 

Type the SRM file specification (including the password if the CREATELINK capability has one). 
D up_ link to what ? 

Type the new file specification. Wildcards can be used in the specification. This puts a link to the 
file in a second directory. If the Move option was requested, the original link is then removed. 

If the file is referenced from two or more directories, the file is physically removed from the disc 
only when all links to the file have been removed. 

You should be aware that new CODE files generated by the Compiler, Assembler and Librarian 
to replace older versions are not written in the same space (unless Overwritten). If several 
directories have duplicate links to the same CODE file and the CODE file is recompiled, only one 
directory has an accurate link to the new CODE file. Other users must use the Duplicate link 
command to become linked to the new CODE file. 



Note 

Using the Duplicate Jink command to "duplicate link" a file to the same 
file results in the file being removed. 

The Duplicate Jink command cannot duplicate links or move files which 
are on different physical volumes. 



132 The Filer 



Extended directory 



The Extended directory command lists the directory of a blocked volume or a set of files in the 
volume. 



(=> 



f 1 le 
spec i f icat ion 



vo 1 ume 
specif icat ion 



K 



K> 



file 
spec i f icat ion 



volume 
specification 



1 mtum 1 or (INTER) 



Y 

dest inat ion 



:h 



Item 


Description/Default 


Range 

Restrictions 


file specification 
volume specification 


literal 
literal 


(See the beginning of 
this section) 

(See the beginning of 
this section) 



Semantics 

The Extended directory prompt: 

List_ext what directory ? 

The Extended directory command requires a legal volume ID or a file specification. Results can 
be listed to the PRINTER: or to a text file if specified and separated from the first specification by a 
comma. If no destination is specified the listing defaults to the CONSOLE. Wildcards are 
available to identify subsets of files on the volume. 

In the listing, the name of the volume is displayed in the upper left-hand corner. To the right, the 
directory type is displayed. Pascal discs have Level 1 directories. Level 1 directories contain the 
creation date and volume size information. Level directories (created on other systems) do not. 
Your directory listing should display the date the directory was created and the date it was 
changed as system volume, the size of the storage blocks, and whether the listing is in storage 
order or alphabetical order. The size of blocks on LIF volumes is 256 bytes. The size of blocks on 
WS1.0 volumes is 512 bytes. The Shared Resource Management system uses single byte 
"blocks". 

To have directories listed in alphabetical order, include [ * ] after the directory name. For example: 

MYDIR: [*] 



The column entries for each file include: file name, number of blocks used for storage, the file size 
in bytes, the number of the block where the file starts, the date the file was changed, the type as 
recognized by the file system, the type-code used by the directory system, SRM access informa- 
tion, the date the file was created and two extension fields. 



The Filer 133 



The SRM access information column comes under the heading "directory info". It contains 
codes which show the public access rights: 



M 


Manager 


R 


Read 


W 


Write 


S 


Search 


P 


Purgelink 


c 


Createlink 



And the current file status: 

CLOSED 
SHARED 
EXCLUSIVE 
CORRUPT 

CLOSED, SHARED and EXCLUSIVE are file status that are associated with SRM systems and 
are explained in detail in Chapter 2. If a file is ever marked CORRUPT, your Shared Resource 
Manager has a problem. Stop your operation and notify the person responsible for your SRM. He 
should restore the SRM to a usable state.) 

The last two lines display additional directory information including how many more entries can 
fit in the directory. The size of a directory is specified when the disc is initialized. 

The results can be listed to a printer or a file if you so specify. The destination of the listing is 
separated from the volume ID or file specification being listed by a comma and, if no destination is 
specified, the listing defaults to the screen. Wildcards are available to specify groups or subsets of 
files on a mass storage medium. 

For example, assuming that SYSVOL: (the system volume) is in the disc drive associated with 
logical unit #3, a listing of all the CODE files on that volume could be sent to the printer by 
specifying any of the following in response to the Extended directory prompt: 

»3:=C0DE>#G: specifies volume residing in unit #3; listing to logical unit #6: (the 

PRINTER: volume) 

* = CODE tPRINTER : specifies system volume; listing to the PRINTER. Without the colon, 

the listing would be sent to a DATA file named "PRINTER" on the 
default volume. 

SYSUOL : =CODE »*G specifies SYSVOL: volume; listing to unit #6. 

In all cases the " = CODE" string refers to all files whose names end in CODE on the specified 
volume and the listing is sent to the printer. 
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Listings can also be sent to a file. Use a destination parameter after the the source parameter 
(separated by a ",") as in the above PRINTER: example. Give a complete file specification. Use 
the appropriate suffix in the file name. Otherwise, a file of type DATA is produced. For example: 

List what directory ? #3 : tSYSUOL : L I ST . TEXT 

or 

List what directory ? »3 : tSYSMOL : LIST . ASC 
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Filecopy 

The Filecopy command copies a specified file, set of files or volume to the specified destination. 



Cs> 



file 
spec i f icat ion 



Vh* 



vo lume 
spec i f icat ion 



o 



^-*\ fBWunT) or [EHTCBl J ' 



file 
spec if icat ion 



volume 
spec i f icat ion 



1 — »•( [Return] or lEWTtBl J — 1*1 



Item 



Description/Default 



file specification literal 

volume specification literal 

Semantics 

The Filecopy prompt: 
Filecopy what file ? 



Range 
Restrictions 



(See the beginning of 
this section) 

(See the beginning of 
this section) 



The Filecopy command is initiated by pressing ( F ) and re qui res two specifications — a source 
and a destination separated by either a comma (,) or [Return] or [ENTER] , The source volume must 
be on-line. The destination volume does not have to be on-line. 

Copying Files 

When copying files, you will need to enter two file specifications, separated by either a comma or 
the [Return] key. The first is the existing file, and the second is the name of the duplicate file. 

Wildcards may be used to specify sets of files. If the equals ( = ) wildcard is used, the copy is not 
confirmed before taking place. Also, note that if the equals wildcard is used alone (i.e., without 
any qualifying strings) then the Filer copies every file on the specified volume. If the question 
mark wildcard is used, you are asked to verify the transfer of each file meeting the wildcard 
specification before the Filecopy takes place. Thus, using the wildcard allows you more flexibility 
and control over the process. 

The dollar sign character ($) may be used in the destination specification to indicate that the file(s) 
will have the same name (or names) as the source file(s). For example, assuming that there are a 
number of TEXT files on the volume TRIG: and that a second volume named MATH: exists, 

TRIG:=TEXT,MATH:$ 

This results in all the files on the TRIG: volume whose file names end with the string TEXT being 
copied to the volume MATH: and given the same name as they have on the TRIG: volume. 

Be sure to use either a file name or the $ character when specifying a destination volume. If, in the 
example above, the destination volume was specified as MATH: instead of MATH:$, the Filer 
would respond: 

Destroy directory of MATH: ? 
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If you respond with ( Y ) , the directory of that volume gets overwritten. Pressing ( N ) aborts 
the Filecopy command and returns the Filer prompt. 

On a system with a single disc drive, the Filecopy command proceeds by reading the specified file 
or files into memory, prompting you to remove that volume and insert the destination volume, 
and then writing the file(s) in memory to the destination volume. Depending on the amount of 
memory in your computer and the amount of material being copied, you may have to swap discs 
more than once. 



Note 

When using the Filecopy command with a single disc drive, wait for 
the Filer's prompt before removing the source volume and replacing it 
with the destination volume. Failure to follow this guideline may result 
in the loss of information from the source volume. 



A size specification may be used in the destination description. For example, specifying: 
SYSUOL:FILE » OTHER VOL : FILE [ 35] 

would result in the file being written to the first available area on OTHERVOL: that was at least 35 
blocks in size. 

Copying BASIC BDAT Files 

The Pascal Filer can also copy BDAT (BASIC Data: file type -5791) files produced by HP BASIC 
Workstation Systems. When copying BDAT files from one LIF volume to another LIF volume, or 
from one SRM volume to another SRM volume, an exact duplicate of the file is made just as with 
Filecopy of other file types. However, the file size changes when BDAT files on LIF volumes are 
copied to SRM volumes, and vice versa. This change is due to these factors: 

• On volumes with LIF directories, BDAT files contain a special "system sector" (256 bytes) 
which describes the file: logical end-of-file pointer, and number of defined records in the file. 
This sector is at the beginning of the data portion of the file on LIF volumes, because there is 
not room for the information in LIF directories. 

• On volumes with SRM directories, BDAT files also have some of this "system" information 
(only the logical end-of-file pointer). However, it is not in the data portion of the file; instead it 
is in the parent directory, which has room for the information. 

Therefore when using Filecopy to copy a BDAT file from from a LIF to an SRM volume, some of 
the "system sector" at the beginning of the LIF BDAT file is moved to the SRM directory. The file 
size, as shown in a Filer directory listing, consequently decreases. Part of this decrease may also be 
due to the fact that the SRM system keeps track of how many bytes were actually written into the 
file, and only allocates enough sectors for them. (The BASIC system, on the other hand, allocates 
as many sectors for LIF BDAT files as indicated by the "number of records" and "record size" 
parameters in the CREATE BDAT statement.) 

Also, when using BASIC'S CAT statement to list the SRM directory, the number of logical records 
("RECS/FILE") may change due to the fact that BASIC calculates this number by dividing the 
physical file size by the logical record size ( ' 'BYTES/REC ' ). 
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Conversely, when using Filecopy to copy BDAT files from SRM to LIF volumes, the logical 
end-of-file information is moved from the SRM directory to the BDAT "system sector" at the 
beginning of the data portion of the file. The file size, as shown in a Filer directory listing, may 
increase due to the movement of this information. 

When accessing BDAT files on LIF volumes with a Pascal program, it is important to note that the 
first sector (256 bytes) of data in the file is the "system sector." You will usually ignore this 
information (unless your program knows how to use it), using only the data in the second through 
the last sectors of the file. 

Copying Volumes 

To make a back-up copy of an entire volume, use the Filecopy command. Simply type in the 
source volume ID and the destination volume ID. The destination volume must be initialized but 
does not have to be Zeroed (the directory gets copied from the source volume). The Filer will ask 
you if you want the directory destroyed. A volume-to-volume copy makes an exact copy of the 
source volume on the destination volume. 

Note that having two volumes with the same name on-line at one time is not advised. The Filer 
looks for volumes according to their volume names and may not be able to distinguish one from 
the other. Thus, the Filer may perform an action on one volume when you wanted the operation 
to affect the other volume. The Filer warns you whenever this condition exists. If you get a 
warning, either remove one of the volumes or use the Filer's Change command to change the 
name of one of the volumes. 

You can copy files on one volume to a volume of a different size but you should not use volume 
IDs alone to do this. If the source volume is larger than the destination volume, the Filer refuses to 
execute the Filecopy. If the source is smaller than the destination, the destination volume ends up 
the same size as the source when the operation is through so you lose storage space. Remember? 
It makes an exact duplicate of the source. 

The best way to handle copies between different size volumes is to use one of the wildcards. Use 
the equals wildcard ( = ) if the destination is larger than the source and the question mark wildcard 
(?) if the destination is smaller than the source. In the latter case you have to be selective in your 
copies since there is not enough space for all of the files. 

When the Filecopy command has finished its task, the screen displays what file(s) or volume has 
been copied and the Filer prompt ap pears. The Filec opy command can be aborted before all 
specifications are complete by pressing ( Return ) or ( ENTER ) in response to the prompt. 
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In cases where the destination volume already contains a file with the same name as the file being 
copied, this prompt is displayed: 

ANYUOL:XFILE 

exists .♦. Remove* Overwrite* Neither ? (R/O/N) 

You have the options: 

• Remove: remove the file before proceeding with the copy operation. 

• Overwrite: replace the contents of the old file with the new information. The Overwrite 
option cannot be used to change the type of a file on SRM. Attempting to do so will result in 
the file contents being inconsistent with the file type. 

• Neither: cancel the operation. 

The Overwrite option allows you to put a file in the same starting location as the original. This is 
important to SRM users when duplicate links exist to a file. All links and passwords to the file are 
accurate when a file is updated because it is put in the same logical location. If you chose the 
Remove option, the original file would not actually be removed; only your link to it is removed. 
The other users are still linked to the original file. 



Note 

Using the Filecopy command to ' 'copy' ' a file name to the same name 
on the same volume results in the file being removed. 



Note 



The Filecopy command does not change the file type 



Note 

Overwrite of a file of type SYSTM is not recommended because the 
start execution address cannot be changed in an existing SYSTM file. 
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Get 



The Get command associates a specified file as the current workfile. 



peci f f 1 i 1 c e ation| - , " C ^"rSJQ -H 



Item 


Description/Default 


Range 
Restrictions 


file specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Get prompt: 
Get what file 



The Get command is initiated by pressing ( G ) and prompts you for a file specification. If a 
workfile currently exists when the Get command is executed, you are asked if you want to release 
that file before being allowed to specify a new workfile. Upon receiving the specification, the Filer 
finds the file (or files) and associates that name with the current workfile. Subsequent operations 
on the workfile use the specified name. The workfile is generally named * WORK. TEXT and/or 
*WORK.CODE. 

The Get operation assumes that the text version of the specified file has a .TEXT suffix. If the text 
version is ASCII, you must include the . ASC suffix. If the text version is DATA, you must include a 
"." at the end of the file name (to prevent the appending of the .TEXT suffix). 

The operating system notes that either a text or code or both versions of the workfile exist. 
Workfiles can only be of type TEXT/ ASCII/DATA or of type CODE. If both text and code versions 
of the specified file exist, both are associated with the workfile; if only one exists, the association is 
made with that file. The Filer reports one of three things: either a text or code file has been loaded, 
both have been loaded or the file cannot be found on the specified volume. 

The Filer is not the only Pascal subsystem where a workfile can be created. The Compiler, 
Assembler and Editor subsystems also create workfiles. Once a workfile exists, it is treated as the 
default file in many of the subsystems. A workfile is "released" by the Filer's New command. 
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Krunch 

The Krunch command moves all files on a block structured volume so that all the unused storage 
space is at the end of the volume. 



C 



CO 
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Item 


Description/Default 


Range 
Restrictions 


volume specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Krunch prompt: 



Crunch what directory 



If there is the slightest question about the reliability of the medium you are using (because of 
excessive wear or damage) , use the Bad sector command to do a scan of the sector on the volume 
before initiating Krunch. If a bad sector is found, use the Filer's Make command to make a file of 
type .BAD over the bad sectors. Krunch does not move files of type .BAD. Moving files onto an 
unreliable area of storage is a good way to lose a file. 



The Krunch command is initiated by pressing ( K ) and it prompts you for a volume ID. After 
you respond with a legal volume ID of an on-line block structured volume, it prompts: 



Crunch directory MKWORK 



(Y/N) 



Where MKWORK : is whatever volume you specified. Typing ( Y 1 for Yes lets the command 
continue; ( N ) for No returns the Filer prompt. The Krunch command executes a sensitive 
operation -- that of moving all the files forward on the disc by reading the files into memory and 
then writing them back out on the disc in such a manner so as to make all the unused space on the 
volume contiguous at the end of the disc. 



Note 

UNDER NO CIRCUMSTANCES SHOULD YOU ATTEMPT TO IN- 
TERRUPT THE KRUNCH OPERATION ONCE IT HAS BEGUN. 
You are risking your directory and thus, all the information contained 
on that medium if you do so. Do not touch the power switch, the door 
on the disc drive or attempt to use the keyboard while a Krunch is 
occurring. 
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This process becomes necessary when, after repetitive reading and writing to the disc, the 
available storage space becomes highly fragmented. The situation can exist where you have 100 
blocks available on the disc but because they are all in 10 or 15 block chunks, there is not enough 
contiguous storage space for the system to write a 20 block file to the disc. 

The Krunch command is extremely useful and using it should not worry you. However, because it 
alters the directory (which maps where the information on the disc resides), it is one of the 
quickest ways to wipe out a volume. The precautions outlined above should help you avoid any 
problems while using the command. 

The Krunch command does nothing on SRM units. 
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List directory 



The List directory command lists directory information about a block structured volume or one of 
its subsets. 



file 
spec i f icat ion 



volume 
specif ication 
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K> 



file 
spec i f icat ion 



volume 
spec i f icat ion 



dest inat ion 



Item 


Description/Default 


Range 
Restrictions 


file specification 
volume specification 


literal 
literal 


(See the beginning of 
this section) 

(See the beginning of 
this section) 



Semantics 

The List directory prompt: 

List what directory ? 

The List directory command requires a legal volume or file specification. Results can be listed to 
the PRINTER: or to a text file if specified and separated from the first specification by a comma. If 
no destination is specified the listing defaults to the CONSOLE. Wildcards are available to 
identify subsets of files on the volume. 

In the listing, the name of the volume is displayed in the upper left-hand corner. To the right, the 
directory type is displayed. Pascal discs have Level 1 directories. Level 1 directories contain 
directory-create and volume size information. Level directories (created on other systems) do 
not. Your directory listing should display the date the directory was created and the date it was 
changed as system volume, the size of the storage blocks, and whether the listing is in storage 
order or alphabetical order. The size r f blocks on LIF volumes is 256 bytes. The size of blocks on 
WS1.0 volumes is 512 bytes. The Shared Resource Management system uses single byte 
"blocks". 

To have directories listed in alphabetical order, include [*] after the directory name. For example: 
MYDIR: [*] 



The column entries for each file include: file name, number of blocks used for storage, the file size 
in bytes, and the date the file was created or changed. 
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The last two lines display additional directory information including how many more entries can 
fit in the directory. The size of a directory is specified when the disc is initialized. You need one 
256 byte block for each eight directory entries. 



For example, initiating the command by pressing ( L ) , specifying ACCESS: and pressing 
( Return ) or (ENTER) results in the following listing appearing on the screen: 

ACCESS: Directory type= LIF level 1 

created 20-Sep-B2 13.57,17 block size=256 

S t o r a 3 e order 

...file name.... * b 1 k s * bytes last c h n 3 

FILER 218 55808 20-Sep-S2 

EDITOR 224 57344 20-Sep-S2 

LIBRARIAN 202 51712 20-Sep-82 

MEDIAINIT.CODE 132 33792 20-Sep-SZ 

TAPEBKUP.CODE 54 13S24 20-Sep-82 

FILES shown =5 allocated=5 unallocated =3 

BLOCKS (256 bytes) used = 830 utilise d = 223 larsest space = 223 

The Extended Directory command gives more information about the files and unused areas on 
the volume. 
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Make 

The Make command creates files and directories. 



(s> 
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Item 


Description/Default 


Range 
Restrictions 


file specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Make prompt: 



Make File or Director; 



(F/D) 



The Make command is useful primarily in two ways. Files can be made when you need to reserve 
physical space on a disc, and directories can be made on an SRM system. 

The Make command is not required to create files to be used by the various Pascal subsystems. It 
reserves space only; it in no way initializes or changes the contents of the space. In the Pascal 
System, each subsystem lets you either create or specify any files you need. Users of HP BASIC 
may quite naturally think that the same function is served by this command as the CREATE 
command in BASIC (where you must create a file before using it). Thus the distinction between 
these similar sounding commands is drawn here. 

The Make command requires at least a file specification (which includes a volume ID by 
definition) and accepts an optional size specification. If the (positive integer) size is given, it must 
follow the file specification on the same line and be enclosed in square brackets. The Filer then 
creates a file with the specified name and of the specified size on the first area of the volume that 
has a large enough area of contiguous storage space to meet the size requirements. 

When using a size specification to make a file, you must be aware that the size is specified in 
"number of blocks". The size of all "Make" blocks is 512 bytes — regardless of the directory 
type. A LIF directory considers a 256 byte sector to be a block. The WS1.0 directory considers a 
block to be 512 bytes. So if you make a file on a LIF volume and specify 500 blocks, it will show 
up in the directory as 1000 blocks. 

For example, assume that there is a volume name d MKW ORK: on-line that has at least 22 blocks 
of contiguous and unused space available. Press ( M ) to initiate Make, specifying: 

MKWORK :DUX.TEXT[22] ( Return ) or [ENTER) 
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This results in a file named DUX. TEXT being created on the first available area with 22 blocks of 
the volume MKWORK: and the Filer reporting the following: 

MKWORK : DUX. TEXT made 

A subsequent listing of the directory (using the List directory or Extended directory commands) 
will show a file of the same name with a 22 block size (on WS1.0 directories). 

The size specification may be omitted in which case the Filer creates the specified file using the 
largest unused area on the disc (i.e., the largest contiguous storage space on the disc will be 
allocated to the file). It is recommended that you specify the size you want the file to be. 

There are two special cases of size specification worth knowing about. The first is the number zero 
enclosed in brackets [ ] which is the same as omitting the size specification altogether — the 
Filer uses the largest space available. The second case is the asterisk character enclosed in 
brackets C * ] which tells the Filer to make the file's size either the second largest area on the disc 
or half of the largest area, whichever is greater. 

The Make command is useful if you must rebuild a file that was lost on a disc. 

1. You must know its size and where it was located. 

2. Then make TEMP files (e.g., TEMPI, TEMP2, etc.) overall the unused spaces on the disc 
that are as large or larger than the file you'll be making. 

3. Then make a file of the proper type over the lost file to recover it. 

4. Finally, use the Filer's Remove command to remove all the TEMP files. 

An Extended directory listing can help you determine the location and size of unused areas on the 
disc. 

The above technique will not recapture lost files on SRM systems. However, the Make command 
is used to create directories on an SRM system. For example: 

Make F r i 1 e or Directory ? (F/D) 

Answer the first question by typing ( D ) and specify where you want the directory located and 
what is its name. The directory path tells where you want it and its name is the name on the end of 
the path. For example, if you had an SRM directory: 

*5: USERS /JOE/ PROJECT 1 
If you wanted to create a directory for Project l's DATA files, you should type: 
#5 : USERS/ JOE/ PROJECT 1 /DATA 
The DATA directory is created in the PROJECTl directory. 
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New 

The New command releases or clears the workfile area. 
(od}-H 

Semantics 

The New command requires no specifications. Upon pressing ( N ) to initiate the command, it 
clears the workfile unless the workfile has been updated since the last Save command. If this is the 
case, the prompt appears: 

Throw away current workfile? ( Y / N ) 



Respondi ng by pressing ( N ) for No allows you to use the Save command to write the file to a 
volume; ( Y ) for Yes clears the current workfile area. When the Filer executes the New 
command, it will respond with: 



WorKfile cleared 



You can check the status of the workfile before using New with the What command. The What 
command gives you the name and status (saved or not) of the current workfile. 

Do not confuse the Filer's New command with the New system volume command at the Main 
Command Level — the two commands are different and perform separate functions. 
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Prefix 



The Prefix command changes the default volume to the one specified. 



(e> 



file 
specific a tion 



K 



volume 
specif ica tion 



[Return] or ( ENTEHJ 



>^ 



Item 


Description/Default 


Range 
Restrictions 


file specification 
volume specification 


literal 
literal 


for SRM only (See the 
beginning of this section) 

(See the beginning of 
this section) 



Semantics 

The Prefix prompt: 

Prefix to what directory ? 



The Prefix command is initiated by pressing ( P ) and requires a volume ID. The command 
allows you to specify a new default volume — the one where the Filer searches for file specifica- 
tions when a volume name is not specified. The volume must be block structured (one used for 
mass storage) but does not have to be on-line. The current prefix (i.e., default) volume can be 
obtained by responding to the Prefix prompt with a colon (: ). (The Volumes command may also 
be used). 

When the command executes, the screen displays the message: 
Prefix is MKWORK: 

Where MKWORK: is the name of the current default prefix. The Prefix command saves keys- 
trokes if you are doing a lot of file accessing on a particular volume. 

Filer commands which request a volume ID may be answered with the colon character (:) which 
specifies the current default volume. 

It is possible to set the default prefix to a flexible disc drive, regardless of the volume inside. This 
is done by typing the following while the drive door is open. 

• 3: (Return) or (ENTER) 
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The prefix command is used to set up a working directory on a Shared Resource Management 
system as well. If you had an SRM file named: 

*5 : USERS/ JOE/ PRO JECT1/ PROGRAMS/ FILE 

Initiate the Prefix command as usual and specify: 

»5 : USERS /JOE/ PRO JECT1/ PROGRAMS 

This sets the SRM volume as the default volume (with volume name of PROGRAMS) and 
USERS/JOE/PROJECT1/PROGRAMS as the working directory on the SRM. Now you can 
specify the file with: 

FILE 

If you were to use the Prefix command again to set the default prefix to another volume (not on 
the same unit), the working directory and volume name for the unit remain PROGRAMS. You 
need only specify: 

#5:FILE 

or 

PROGRAMS:FILE 

Either will get the same file. 



Note 

Do not use the Prefix command on unit #45. This is the system 



volume and should not be altered. 



It is possible to change the working directory on an SRM unit without changing the default 
volume. Use the Filer's Unit directory command. Press ( U ) and then give the directory name 
that you wish to become the working directory. If the new directory is in the existing working 
directory, just type the new directory name. If it is not, type the whole directory path as shown 
above in the Prefix example. 
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Quit 

The Quit command exits the Filer subsystem and returns control to the Main Command Level. 



(cb) -h 
Semantics 

The Quit command has no parameters and no specifications of any type are needed. Pressing 
( Q ] exits you from the Filer and the Main Command Prompt is displayed on the screen. 
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Remove 

The Remove command purges specified files from the directory. 
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f ale 
spec if icatjon 



Item 


Description/Default 


Range 
Restrictions 


file specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Remove prompt: 
Remove what file 



The Remove command is initiated by pressing ( R ) and requires a file specification. The 
command removes the specified file from the directory, updates the directory and reports the 
action it has performed. Wildcards may be used to specify a subset of files to be removed. If the 
equals wildcard ( = ) is used in the file specification, the Filer reports the specified file or files and 
then prompts: 



Proceed with remove 



( Y / N ) 



This is the last chance you have to change your mind about the re moval. Pressing ( N ) for No 
aborts the operation and no files are removed. Pressing ( Y ) for Yes removes those files 
meeting the wildcard specification from the directory. The process is not always reversible. 
However, the Make command can sometimes be used to recover a removed file. 



Note 

The Filer considers the file specification = to specify ALL the files on 
the default volume and MKWORK: = to specify ALL the files on the 
MKWORK: volume. If you use the wildcard in this form and respond 
to the Fi ler's prompt (Proceed with remove ? (Y/N))with 
a ( Y ) for Yes, every file on t he dire ctory of the specified volume is 
removed. Responding with a [ N ) for No aborts the operation. 
Wildcards can be hazardous to your files — watch the prompts. 



Specifying a single file (of an on-line volume of course) in response to the Remove prompt results 
in the removal of that file from the directory and a report that the file has been removed. Once the 
( Return ) or (ENTER) key is pressed following the file specification (unless wildcards are used), that file 
is gone. 
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While the use of the equals wildcard ( = ) results in being prompted for whether or not you want 
the directory updated, the question mark wildcard (?) acts slightly differently. It allows you to be 
more selective in your removal. Given the volume PROCESS: containing the files: 

NOYMEMO.TEXT 
MARKLTR.TEXT 
PARSER. TEXT 
PARSER. CODE 
GARBAGE. TEXT 

The specification PROCESS:?TEXT in response to the Remove prompt results in the screen 
clearing and the following message appearing. 

Remove NOVMEMO . TEXT ? (Y/N) 



Answering with either a ( Y ) or ( N ) results in the next prompt appearing below the first: 
Remove MARKLTR.TEXT ? (Y/N) 

The process continues until you have been prompted for all the TEXT files on the PROCESS : 
volume and then the final prompt appears: 

Proceed with remove ? (Y/N) 

You may be respond with either a [ Y ] (for Yes) o r ( N ) (for No). The files are not actually 
removed until this prompt is answered with a ( Y ) . The ? wildcard thus allows you to be both 
selective and relatively safe about your file removals. 

The Remove operation treats SRM directories like files if they are empty. Remove is not allowed 
on non-empty SRM directories. 
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Save 

The Save command saves the current workfile on the specified volume. 
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Item 


Description/Default 


Range 
Restrictions 


file specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Save command is initiated by pressing ( S ] and may or may not require a file specification. 
If the workfile was never updated, it is automatically saved with the original name. 

If the workfile was previously named using the Save command, or originally obtained using the 
Get command, then the Filer prompts: 



Save as PREVIOUS . TEXT 



(Y/N) 



Where P R E V 1 U S 4 T E X T is the name previously associated with the workfile. Responding with a 
( Y ) for Yes results in either a CODE or TEXT file (or both, depending on what is in the 
workfile) of that name being removed and replaced with the current workfile. 



If the workfile is not named, or if you answer ( N ) , the Filer prompts: 
Saue as what file ? 

When naming the file, the following conventions apply to the type of the file: 

1. If a standard suffix is recognized, the workfile is either Filecopied, Translated or Changed 
(on the system volume) to the file name and type. 

2. If no suffix is recognized, a .TEXT file is the default. 

3. If no suffix, but a "." is found, the file type is DATA. 

4. The .CODE file is created by removing the suffix (if there is one) and adding .CODE to the 
file name. 

The Filer displays that the file is now saved. 

To find out what the current name and state (saved or not) of the workfile is, use the What 
command. 
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Translate 

The Translate command converts text files between the TEXT, ASCII, and DATA formats. 
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file specification 
volume specification 


literal 
literal 






(See the beginning of 
this section) 

(See the beginning of 
this section) 



Semantics 

The Translate prompt: 

Translate what file ? 



The Translate command is initiated by pressing ( T ) and requires two specific ations — a sourc e 
and a destination separated by either a comma (,) or a carriage return (press (Return) or (ENTER) ). 
The source specification can be any block structured volume, any file or any group of files on a 
volume. The destination specified can be any of the above and may also be a non-block 
structured volume (i.e., the PRINTER : or CONSOLE : ). Non-block structured volumes (like the 
PRINTER: ) are assumed to be on-line. 

Wildcards may be used to specify sets of files but if a wildcard is used in the source specification, 
either a wildcard or the $ character (discussed below) must be included for the destination. If the 
equals wildcard ( = ) is used, the translate is not confirmed before taking place. Also, note that if 
the = wildcard is used alone (i.e., without any qualifying strings such as LI BR, TEXT, etc.) then 
the Filer Translates every file on the specified volume. If the question mark wildcard (?) is used, 
you are asked to verify the translate of each file meeting the wildcard specification before the 
Translate takes place. Thus, using the ? wildcard allows you more flexibility and control over the 
process. 

The dollar sign character ($) may be used in the destination specification to indicate that the file(s) 
will have the same name (or names) as the source file(s). For example, assuming that there are a 
number of TEXT files on the volume TRIG: and that a second volume named MATH : exists, 

TRIG:=TEXT ,MATH:$ 

This results in all the files on the TR I G : volume whose file names end with the string TEXT being 
translated to the volume M ATH : and given the same name as they have on the TR I G : volume. 
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On a system with a single disc drive, the Translate command proceeds by reading the specified 
file or files into memory, prompting you to remove that volume and insert the destination volume, 
and then writing the file(s) in memory to the destination volume. Depending on the amount of 
memory in your computer and the amount of material being translated, you may have to swap 
discs more than once. 



Note 

When using the Translate command with a single disc drive, wait for 
the Filer's prompt before removing the source volume and replacing it 
with the destination volume. Failure to follow this guideline may result 
in the loss of information from the source volume. 

The Translate command allows the translating of files or groups of files to non-block structured 
devices like the PRINTER: and CONSOLE:. Only text (TEXT, ASCII, DATA) files should be sent 
to printers since other files are not generally human readable. 

When the Translate command has finished its task, the screen displays what file(s) have been 
translated and the Filer prompt ap pears. Th e Tran slate command can be aborted before all 
specifications are given by pressing ( Return ) or (ENTER) . 

In cases where the destination volume already contains a file with the same name as the file being 
Translated, this prompt is displayed: 

ANYUOL:XFILE 

exists .,, Remove* Overwrite* Neither ? (R/O/N) 

You have the options: 

• Remove: remove the existing file before proceeding with the translation. 

• Overwrite: replace the contents of the old file with the new information. The Overwrite 
option cannot be used to change the type of a file on SRM. Attempting to do so will result in 
the file contents being inconsistent with the file type. 

• Neither: cancel the operation. 

The Overwrite option allows you to put a file in the same starting location as the original. This is 
important to SRM users when duplicate links, passwords, etc. exist to a file. All links and 
passwords to the file are accurate when a file is updated because it is put in the same logical 
location. If you chose the Remove option, the original file would not actually be removed; only 
your link to it is removed. The other users are still linked to the original file. 
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Unit directory 

The Unit directory command changes the volume name and working directory for an SRM unit. 
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file 
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volume 
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Item 



file specification 



Description/Default 



literal 



Range 
Restrictions 



(See the beginning of 
this section) 



Semantics 

The Unit directory prompt: 

Set unit to what directory ? 

The Unit command changes the working directory on SRM units. The working directory and the 
volume name for SRM units are the same. The Prefix command performs the same operation but 
sets the default volume to the SRM volume. The Unit command does not. 

To specify the working directory, you must start either from the existing working directory or from 
the root directory. 

To get to the root, an SRM volume identifier must be given or the default is assumed. Follow the 
volume ID with "/". This positions you in the root directory. 
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From the working directory, you can continue down the tree structure from directory to directory 
or you can go back up the structure one directory at a time using ". . " for the parent of the current 
directory. 

For example, if the present working directory for unit #5 is: 

USERS /JOE/ PRO JECT1 /PROGRAMS 

and you wanted the new working directory to be: 

USERS /JOE/ PRO JECT5/ DOCUMENTS 

you can specify it in one of the following ways. 

*5: /USERS /JOE /PROJECTS /DOCUMENTS 

or: 

PROGRAMS: /USERS /JOE /PROJECTS /DOCUMENTS 

or: 

«5: . . /. ./PROJECTS /DOCUMENTS 

or: 

PROGRAMS: . . /. . / PRO JECT5/ DOCUMENTS 
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Volumes 

The Volumes command lists the volumes currently on-line. 



Semantics 

The Volumes command requires no specifications. Upon pressing ( V ) it displays the following 
information about all on-line volumes currently associated with the Pascal System: the logical 
unit number associated with a volume, whether the volume is the system (boot) volume, a block 
structured volume or a non-block structured volume, the volume's name, and the current Prefix 
or default volume. 

This is a typical display generated by the Volumes command: 



Volumes on-line: 


1 


CONSOLE: 


*■? 


SYSTERM: 


3 » 


MINI3: 


4 # 


HINI4: 


5 * 


MY_SRM: 


G 


PRINTER: 


45 * 


SYSTEMQ4: 


Prefix 


is - MY-SRM: 



The number on the far left is the logical unit number associated with the volume. The * character 
in the second column indicates the system volume which is always block structured. The « 
character indicates all other block structured volumes currently on-line. The remaining volumes 
(shown with no character in the second column) are non-block structured. The last line of the 
display shows the current default volume. It is where the system looks for a file when no volume 
has been specified. 

The above configuration shows two 3.5 or 5.25-inch flexible disc drives associated with units #3 
and #4 and two SRM volumes associated with units #5 and #45. Respectively, they are the 
working volume and system volume. 
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What 

The What command displays the name and state (saved or not) of the workfile. 



(CiD) -H 

Semantics 

The What command is initiated by pressing ( W ) and requires no other input. The command 
shows the name of the current workfile or indicates that it is not associated with a file name. It also 
shows whether or not the workfile has been saved since the last update to the file. If no workfile 
exists, the Filer responds with: 

No workfile 

Suppose you had two files named INF R ARED. TEXT and INFRA R ED. CODEon the default or 
prefix volume. Assume that you used the Filer's Get command and specified INFRARED to 
associate the files with the workfile. If you then edited the TEXT version of that file (using the 
Pascal Editor), returned to the Filer and executed the What command, the screen would display: 

Workfile is INFRARED (not saved) 

because the workfile was changed since the last time a Save command was executed. 

Saving the workfile does not change the fact that the workfile exists. It is still there. The New 
command is used to clear the workfile. Saving the workfile is not remembered between separate 
sessions of the Filer. If you Save the workfile during the current Filer session, a New command 
immediately clears the workfile. If you Save it, quit the Filer and then return to use the New 
command, the Filer will ask: 

Throw away current workfile ? ( Y / N ) 
even though you saved it during the previous Filer session and haven't updated it since. 
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Zero 

The Zero command creates an empty directory on the specified volume. The Zero command is 
not allowed on SRM volumes. (See the Make command.) 



C^ HspecYA^tionl - K SgorSS ) ~H 



Item 


Description/Default 


Range 
Restrictions 


volume specification 


literal 


(See the beginning of 
this section) 



Semantics 

The Zero prompt: 

Zero directory (NOT valid on SRM type units) 
Zero what directory ? 



The Zero command is initiated by pressing ( Z ) and requires the volume ID of a block 
structured volume. The volume must be formatted using the Pascal utility program 
MED I A I N IT . CODE supplied on the ACCESS : volume. 

Since the Zero command creates an new empty directory on the volume, you will be prompted: 

Destroy THISYOL: ? (Y/N) 



Responding with a ( N ) for No aborts the command and returns the Filer prompt. 



If you answer ( Y ) , the next prompt is: 

Number of directory entries ( 8 ) 



The n umber in the parentheses is the number in the existing directory. Respo nd with (Return) or 
(ENTER) if that is the number you want. If there is no number in parentheses, (Return) or (ENTER) 
causes the default number for that directory type (80 for LIF; 77 for WS1.0) to be put on the disc. 
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The next prompt is: 

Number of bytes (27033G) ? 

It is asking for the logical size of the disc (the extent to be managed by the directory). The n umber 
in the parenthesis is the number in the existing directory or the default for that disc. Press ( Return ) 
or (ENTER) to use the displayed number. 

The next prompt is: 

N e g m o 1 u w e n awe ? 

The Filer is asking for a legal volume name. Volume name formats vary with different directory 
structures. LIF directories allow up to six characters with upper and lower case characters being 
distinct. WS1.0 directories allow up to seven characters and all are made upper case. 



An answer of ( Return ) or (ENTER) aborts the Zero command. 

After typing a volume name, the final prompt appears: 

NEWSTUF: correct ? 



Responding with ( N ) aborts the Zero command. Responding with ( Y ) results in the 
message: 

NEWSTUF: zeroed 

Where NEWSTUF: is the name of the new volume. The Filer prompt reappears when the 
operation is complete. 



Note 

Because the file system works with volume names, a LIF volume 
whose name is all blanks (ASCII spaces) will not be recognized as a 
valid volume. 
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Chapter 



Introduction 

This chapter describes the Workstation Pascal Compiler, another subsystem of the Workstation 
Pascal System. It shows how to use the Compiler to prepare Pascal source programs for execution 
on the Workstation System. 

The Workstation Pascal Compiler supports a generous set of Pascal language features. They are 
briefly described in the "Overview of Workstation Software Features" chapter. Further details of 
the language features available on this system are referenced in that chapter. 

Two slightly different compilers are shipped with the Workstation System: 

• COMPILER produces object code for all the processors in the MC68000 processor family (be- 
cause it generates only MC68000 instructions). 

• C0MPILE20 produces machine-specific object code for the MC68020 processor (the MC68000 
and MC68010 processors cannot execute these instructions). 

Preparing a program for execution on this system is a simple process. First, produce source text 
file(s), usually with the Editor subsystem. Then use one of the two compiler subsystems to generate 
an output file of relocatable object code. This output file is ready to be linked and run with the Run 
command - normally there is no explicit link step. 

Compilation speed depends on the storage medium where the source and object code reside. 
Using floppy discs, about 1600 lines per minute (1pm) is typical. If the files are memory-resident, the 
rate is around 4000 1pm. The Compiler's speed contributes significantly to the interactive and crisp 
feeling of the Workstation Pascal environment. 

The Compiler, supported by other subsystems, provides complete facilities for the creation, mainte- 
nance and use of software libraries. Modules of Pascal code can be compiled, stored in the System 
Library, and automatically accessed by any program which needs them. Compiled modules carry 
along a detailed specification of their interface which allows any other program or module to use the 
code or data structures they declare. 
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Steps In Program Development 

This section will teach you by example the steps required to compile and run a simple program. 
You need to know how to use the Editor before you can proceed with this material. We begin at the 
Command level of the system, with no workfile present. 

Prepare the Source Program 

First we need a program to compile. Enter the following program using the Editor. The Compiler 
isn't particular about margins, so you can adjust the program to the left margin as you type. Try to 
preserve the indentation, to keep the program easily readable by mortals. 

Notice that the word "end" is intentionally misspelled at the bottom of the program. Type it just as 
shown, so you can see how errors are handled. 

When you leave the Editor (Quit command), you should specify that the output is to be Written to 
the file "HOWDY". Don't make a workfile (don't use the Update option). 

p r o i r am houdv (input loutput) ! 
type 

color = ( red toranJe lyelloui-ireen) i 
u a r 

hue: color! 

t : inteieri 

procedure show (c:color)i 
b e S i n 

w r 1 1 e 1 n ( o u t p u t i ' H o u d y ! ' to) i 

i : = i + 1 ! 
end! 

b e 4 i n 

writelntoutput) i i : = i 

for hue := red to Jreen do 
s h o u ( h u e ) ! 
e m d . 

At this point, if you use the Filer to examine the directory of your default volume, you'll see the file 
"HOWDY.TEXT" . 

Invoke the Compiler 

The Compiler is invoked by typing the ( C ) key when the system is at the Main Command 
Level. At the time you booted up, the system looked for the Compiler on all the mass storage 
volumes which were on-line. If the Compiler was found at that time, it is expected to still be in 
the same volume whenever it's needed. If the Compiler wasn't found, the system will try to run 
CMP:COMPILER (or the file specified with the last What command). 



So if you press ( C ) and the system re spond s that it can't load the Compiler, you must first 
put the CMP: disc in a drive, then press ( C ] again. 

It takes a few seconds for the Compiler to load from a floppy disc. Then it will ask you, 

Compile what text ? 
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If you had to swap discs, you should remove the CMP: disc and put back the default volume. 
Now respond: 



HOWDY ( Return ) or (ENTER) 

The Compiler automatically appends the ".TEXT" suffix to the name you give; you need not 
do so yourself. Next you are asked, 

Printer listing ( 1 / v / n / e ) ? 



If you have no printer, you must answer ( N ) for no listing or ( L ) for a listin g file. If you've 
got a printer, the ( Y ) response gets you a complete listing. Answering ( E ) w ill get you a 
listing only of any errors which are detected. For the moment, let's answer ( N ) and get no 
listing. Finally the Compiler asks: 



Output file (default is "HOWDY . CODE" ) ? 



Respond to this by pressing ( Return ) or (ENTER) to accept the default. 

As the Compiler runs, you can observe its progress through the source program. Each dot 
displayed represents five lines of the source text which have been scanned. Whenever the body 
(the "begin") of a new procedure is reached, that procedure's name is displayed on the screen 
along with an estimate (in square brackets) of how much memory is still available for the 
Compiler to use. The Compiler reads through an entire procedure body before generating any 
code; if you write very large procedures, you may notice the stream of dots hesitating momen- 
tarily at the ends of some of them. 

When the misspelled word "emd" is encountered, the Compiler will beep and display the 
offend ing lin e. You no w hav e three opt ions: press the space bar to continue compiling, hold 
down ( SHIFT ) and press ( Select ) ( ( EXECUTE ) ) to termin ate th e compilation, or enter the Editor to fix 
the mistake. You should select "Edit" by pressing ( E ) . 

Note 

The Editor must be Permanently loa ded, or the volume containing the 
Editor must be on-line to use the ( E ) option when exiting the 
Compiler. 

Handling Syntax Errors 

If the Compiler is printing a listing, it will report errors on the printout, rather than interactively, 
giving you an opportunity to edit the program. In this case, you must call the Editor yourself after 
the compilation is finished. 

When the Compiler points out a syntax error, the place it indicates is not necessarily the place 
where the error occurred; rather, you are shown where the error was first recognized. An easy way 
to get extreme examples of this is to accidentally have unbalanced "begin" and "end" pairs in a 
deeply nested program. The imbalance may be syntactically (though not visually) undetectable 
until much later in the program. Compilers don't see what you mean, only what you write. 
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The error message may not seem reasonable to you. For instance, your misspelled "end" looks 
to the Compiler like an undeclared identifier which may be the beginning of an assignment 
statement. The Compiler sees no similarity between "end" and "emd". 

When an error is detected, the Compiler tries to recover by making an assumption about what 
you meant. Frequently the assumption is wrong, which leads to further errors being reported in 
the vicinity of the first one. Sometimes the Compiler will try to recover by skipping text until it 
sees a keyword or other symbol it recognizes. 

Back to the example: you elected to edit the program, so the Compiler terminated and the 
Editor is now invoked. The file containing the offending line is automatically brought in, and the 
cursor is placed where the error was reported. Simply fix the misspelling and quit the Editor, 
using the Save option to rewrite the corrected file under its original name, "HOWDY". 

Repeat the steps above to compile HOWDY again. If you have a printer, this time you should 
ask for a listing. If there are no other accidental errors, the compilation will succeed this time. 
Your printout should look like this: 

Pascal [Reu 2,0 10/19/82] HOWDY. TEXT 19-0ct-82 14:0B:32 PaSe 1 

1 : D p r o 9 r a m h o w d v ( i n p u t t output)! 

2 : D 1 t v p e 

3 : D 1 color = ( r e d > o r a n s e > v e 1 1 o w > 3 r e e n ) i 
il : D 1 u a r 

5:D -2 1 hue: color! 

G:D -G 1 i: integer! 

7:S 

8:D 1 procedure show (c:color)i 

9 : C 2 b e 3 i n 

1 : C 2 w r i t e 1 n ( o u t p u t t ' H o w d v ! ' i c ) ! 

1 1 :C 2 l : = i + 1 i 

1 2 : C 2 end! 
13:9 

1 a : C 1 b e s i n 

1 5 : C 1 uriteln(output) i i : = ! 

1 G : C 1 for hue : = red to Jrsen do 

1 7 : C 2 5 h o w ( h u e ) i 

1 8 : C lend. 

No e r r o r s • No warnings. 

Interpreting the Compilation Listing 

The column of numbers at the left enumerates the lines. "D" next to the line number indicates the 
line is a declaration; "S" indicates the line was skipped altogether, either because it's blank, or 
because it is entirely within a comment. "C" indicates the line is part of the body of a Pascal block. 

The two numbers, -2 and -6, provide information about where the variables "hue" and "color" will 
be stored in memory. More detailed information about this can be requested by the $TABLES$ 
Compiler option. 
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The column of numbers immediately to the left of the program text shows how deep structures in 
the program are nested. This can be very useful when begin's and end's get out of balance. The 
main program is at level 1 , with procedures nesting successively deeper. The structural nesting of 
complex statements such as for-loops, if s and with's is also counted. 

Running the Compiled Program 

If you use the Filer to look at the directory of your default volume, y ou'll s ee t hat the re are two 
HOWDY files now: HOWDY. TEXT and HOWDY.CODE . Press the QD or Q§D key. The 
operating system remembers the name of the most recently compiled file. You'll see the 
message, 



Load in* 'HOWDY.CODE' 
The program runs, producing this display on the screen: 



Command: Compiler Editor Filer Initialise Librarian Run eXecute Version ? 

Howdv! RED 

Howdy! ORANGE 

Howdv! YELLOW 

Howdv! GREEN 

You ca n also run the program by using the eXecute command: press the ( Select ) ( ( EXECUTE ) ) or the 
[ X ) key. Then when asked 

Execute what file ? 

answer 



HOWDY (Return) or [ENTER] 

Try it now. Actually, you can eXecute any program, not just the one you most recently com- 
piled. Also, if you use the Run command when you haven't compiled any program, the 
behavior is as if you used the eXecute command. 

Using a Workfile 

The Compiler's behavior depends somewhat on whether you are compiling a workfile, or some 
other source file. If you use a workfile, you are asked fewer questions by the Compiler and Editor; 
in fact, while the workfile is present you can't compile or edit any other file! This kind of abbreviated 
behavior may be a blessing or a curse, depending on your needs. 

Workfiles are most useful when you're writing a small program and you're in a hurry. In that case 
you'll appreciate the convenient reduction in keystrokes needed to compile and run the program. 
On the other hand, experienced programmers developing complex systems with many source files 
almost never use workfiles. 
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Workfiles are not particularly useful unless the Editor has been permanently loaded, or the volume 
containing the editor is on-line. This is particularly important in systems which have no external 
mass storage. 

There are two ways to tell the system to use a workfile. You can create one by using the Update 
option when quitting the Editor; a workfile made this way will always be called WORK. TEXT, and it 
will be stored in the system volume. Alternatively, you can designate some existing file as the 
workfile by using the Filer's Get command. The Update option and the Get command are ex- 
plained in the Editor and Filer chapters of this manual. 



Let's make a workfile of HOWDY using the Editor. Press the ( E ) key, and answer that you want 
to edit HOWDY. Immediately use the Quit command, and select the option to Update the workfile. 
This makes a copy of your original source file (but not of the code file). Note that the system volume 
must be on-line at this point, since that is where the workfile is kept. 



Now press ( R ) . If the Compiler isn't on-line, you will need to insert the CMP: or CMP20: disc 
into a drive first. If you swapped discs, then the Compiler is loaded and will say: 

Mount *WORK.TEXT and press (space) 

As you can see, the Compiler knows it's supposed to compile the workfile, and you must put 
your system volume back in the drive. If the Compiler was already on-line, only one question is 
asked after you press ( R ) : 

Printer listing ( 1 / v / n / e ) ? 

Probably you'll answer no. The program then compiles, producing WORK. CODE, and im- 
mediately runs. 



To execute it again, just press ( R ) . It won't be recompiled unless you use change it with the 
Editor. If you aren't convinced it actually ran again (it happens pretty fast), press the space bar to 
clear the screen before running it again. 

Debugging 

The Debugger subsystem is described in detail in a later chapter of this manual. 



Note 

With Pascal 3.0 and later versions, the Debugger is not automatically 
loaded when the system is booted. You will need to load it if you want 
to use it. See the "Debugger" chapter for loading instructions. 
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Modules 

A module is a program fragment which can be compiled independently and later used to complete 
otherwise incomplete programs. For example, you might want to define a "complex number" data 
type and some relevant functions, then use those definitions in several programs. This section 
introduces the concepts and facilities you will need to define, debug and use module libraries. 

Modules, like almost everything else in Pascal, must have all their relevant features and characteris- 
tics declared before use. Diagrams precisely detailing the syntax of a module declaration can be 
found in the HP Pascal Language Reference; an informal presentation is more suitable for present 
purposes. 

Module Structure 

The four parts of a module are its heading, the import and export sections, and its implement part. 

• The heading introduces the module and names it. The name is an ordinary Pascal identifier. 
Example: 

module complex math 5 

• The import part names all other modules on which the present one depends. One module 
depends on another if the dependent module makes use of things exported from the imported 
one: calling procedures, assigning to exported variables, or declaring variables of an exported 
type. The names are separated by commas and the list ends with a semicolon: 

import complex math ^conversions 5 

There is no import part if the module is independent of all others. 

• The export part defines the constants, types, variables, procedures and functions which this 
module will supply to any program or module importing it. Constants, types and variables are 
declared just as in a program or procedure block. Procedures and functions are presented as 
headings without bodies. 

export 

const pi = 3.14159! 
type 

polar = record radius ttheta: real end? 
u a r 

seal ef actor: real 5 

origins polar! 
function maKepolar (a: complex): polar! 
procedure setorisin (a: complex)! 

The export part may make use of things in turn exported from other modules listed in the 
import part, such as the type "complex". Every module must have an export part. 
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• The implement part consists of the reserved word IMPLEMENT, followed by constant, type, 
variable, procedure and function declarations, followed by the word END. All the procedures 
and functions whose headings were in the export part must be present in their entirety in the 
implement part. The implement part may make use of things in turn exported from other 
modules listed in the import part. 

A module does not have to export procedures or functions, it may be used simply to create 
data types. In such a case there will be nothing between the words IMPLEMENT and END. 

A complete module, "complexmath", is shown on the next page. It has no import part because it 
depends on no other modules. (The module is also on the DOC: disc; the source is called CXMO- 
DULE.TEXT.) 

The import and export parts are said to define the module's interface to other modules or prog- 
rams. This interface is public: the information it contains is available to any imported of the module. 

The implement part is said to be "private", which means that everything between the words 
IMPLEMENT and END is hidden from importers. Anything declared here is unknown outside the 
module, except for procedures and functions whose headings were also included in the export part. 

The private and public parts of the module are separated in this way so that its implement part can 
safely be changed without altering programs or other modules which import it. This independence 
of modules from programs is a key to developing software libraries. Another implication is that 
modules can only be dependent on other modules, not on programs. The reason is simply that 
there's no way to import a program into a module (since programs have no export declarations). 

It was stated at the outset that a module is a "fragment" of a program. To be more precise, a 
module is a set of global (outer level) declarations which can be compiled once, then bound into a 
program by an IMPORT declaration in that program. 
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Pascal [Rev 2.0 10/19/82] CXMODULE.TEXT 19-0ct-B2 09:09:35 PaSe 1 

1:D module complexmath! 

2:D 1 export 

3:D 1 type 

4:D 1 complex = record 

5:D 1 re : real i 

G:D 1 im: real i 

7:D 1 end? 

8:D 1 const 

9:D 1 zero = complex [re:0.0tim:0.0]i 
10:S 

1 1 : D 1 function equal (atb: complex): boolean! 

1 2 : D 1 function add (atb: complex): complex! 

13: D 1 function mul (atb: complex): complex! 

14: D 1 function dud (atb: complex): complex! 

1 5 : D 1 function conj (a: complex): complex! 

1B:D 1 function mas (a: complex): real! 

17 : D 1 function scmul (scale:reali a:complex): complex! 
18:S 

19:D 1 implement 

20 :D 1 

21 sD -32 1 function equal (atb: complex): boolean! 

22:C 2 beJin equal := (a.re^b.re) and (a.im=b.im) end! 

23:S 

24:D -32 1 function add (atb: complex): complex! 

25:C 2 besin add. re := a.re + b.re! add.im := a.im+b.im end! 

26:S 

27:D -32 1 function mul (atb: complex): complex! 

28:C 2 besin 

29:C 2 mul. re := ( a. re*b . re-a. im*b . im) ! 

30:C 2 mul.im : = ( a. re*b . im+a. im*b . re ) ! 

31 :C 2 end! 

32:8 

33:D -32 1 function dud (atb: complex): complex! 

34:D -40 2 war denom: real! 

35:C 2 beiin 

36:C 2 denom := si r( b . re )+sq r( b . im) ! 

37:C 2 if denom = 0.0 then halt(-5)i (#diuide by zero*) 

38:C 2 dud. re := (b.re*a.re + b.im#a.im) / denom! 

39:C 2 dud.im := (b.re*a.im - b.im*a.re) / denom! 

40:C 2 end! 

41:8 

42:D -IB 1 function cond (a: complex): complex! 

43:C 2 besin cond.re := a. re! conJ.im := -a.im end! 

44:8 

45:D -IB 1 function mas (a:complex): real! 

4B:C 2 beiin mai := sq rt ( sq r(a. re )+sq r( a. im) ) end! 

47:S 

48:D -24 1 function scmul (scale:reali a:complex): complex! 

49:C 2 besfin 

50:C 2 scmul. re := scale*a.re! 

51 : C 2 scmul. im := scale#a.im 

52:C 2 end! 

53:S 

54:C 1 end. (*complexmath*) 

No errors. 
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Developing and Testing a Module 

The Workstation environment supports a structured approach to the development and testing of 
software modules. This is important because modules often become part of the system library, and 
many programs may depend on them. The usual steps in the development cycle are: 

• Decide what the module will do - define its functionality. Write the interface part first, specify- 
ing what other modules will be needed and what things the module will export. Remember 
that when the finished module is imported into a program, only this interface will be "visible". 
Figure out how a program will use the exported things to get the module to do its job. 

• Decide how the module will be tested. Write a test program which will thoroughly exercise it. 

• Write the implement part of the module. Embed the completed module in the test program, 
and compile the two together. Leave the module inside the program until you're satisfied with 
the results. 

• Extract the module from the test program. This can be done by using the Librarian to pull it out 
of the compiled test program, or by separating the module's source text with the Editor and 
compiling it independently. 

• Use the compiled module. It can be put in the current system library (which is normally the 
LIBRARY file), or left as a user library which is manually linked to dependent programs, or 
loaded into memory by the Permanent load command. 



The following listing shows the source of CXMODULE embedded into the program called CX (also 
on the DOC: disc): 



Pascal [Rev 2.0 10/19/B2] CXO.TEXT 



19-0ct-82 09:15:51 PaSe 1 



3 

a 

5 

B 

7 

B 

9 

10 

1 1 

12 

13 



14:D 

15:D 



IB 

17 

IB 

19 

20 

21 

22 

23:D 

24:C 

25 

2S 

27 

28 

29 

30 

31 

32 

33 

3^ 



prosram ex (listins)! 

1 module complexmathi 
1 export 

1 type 

1 complex = record 

1 re : re al ! 

1 l in : real! 

1 end i 

1 const 

1 zero = complex [re:0.0iim:0.0]! 



function 
function 
f unc t i on 
f unc t i on 
f unc t i on 
f unc t i on 
f unc t ion 



equal 
add 
mul 
dud 
con J 
ma 3 
s c m u 1 



( a >b: 
(a ib: 
(a ib: 
(a ib: 



compl ex ) : 
compl ex ) : 
compl ex ) : 
compl ex ) : 



( a : complex): 
( a : compl ex ) : 



boolean! 
complex i 
complex i 
complex i 
compl ex i 
real ! 



(scale:reali a:oomplex): complex! 



1 implement 
1 

-32 1 function equal <aib: complex): boolean! 

2 besin equal := (a.re=b.re) and (a.im=b.im) end! 

-32 1 function add (aib: complex): complex! 

2 besin add. re := a.re+b.re! add.im := a.im+b.im end! 

-32 1 function mul (aib: complex): complex! 

2 besin 

2 mul. re := ( a . re*b ♦ re-a . im*b . im) ! 

2 mul.im := ( a . re*b . im+a . i m*b . re ) ! 

2 end! 
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Pascal [Rev 2.0 10/19/82] CXO.TEXT 



19-Oct-BZ 09:15:51 Pase 1 



35:D 
36:D 
37:C 
3B:C 

39 :C 

40 :C 
41:C 
42:C 
43:S 

na-.D 

45:C 
4S:S 
47:D 
4B:C 
49:S 

50 :D 

51 :C 

52 :C 

53 :C 
54 
55 
5B 
57 
58 
59 



B0:S 
B1:D 
B2:S 
S3:D 
64:D 



65:D 
66 :D 
B7:D 
B8:0 
B9:D 
70:D 
71 :D 
72:S 
73:C 
74:C 
75:C 
7B:C 
77:C 

78 :C 

79 :C 
B0:C 
B1:C 
B2 
B3 
B4 
85 
B6 
87 
88 
89 
90 
91 



-32 1 function dud (a»b: complex): complex! 

-40 2 war denom: real ! 

2 b e «f i n 

2 denom := si r(b . re)+sq r(b. im) i 

2 if denom = 0.0 then halt(-5)i (*diuide by zero*) 

2 dud. re := (b.re*a.re + b.im*a»im) / denom! 

2 dud.im := (b.re*a.im - b.im*a.re) / denom! 

2 end i 

-IB 1 function conj (a: complex): complex! 

2 b e 3 i n con J. re := a. re! conj.im := -a.im end! 

-IB 1 function ma3 (a:complex): real! 

2 be3in ma«f := sqrt( sir( a. re)+s<=ir( a. im) ) end! 

-24 1 function scmul (scale:real! a:complex): complex! 

2 b e 3 i n 

2 scmul. re := scale*a.re! 

2 scmul. im := scale*a.im 

2 end! 

1 end! (*complexmath*) 



1 import complexmath! 

const 

pi = 3,141592654! 
nsteps = IB! 
uar 

-32 1 atb: complex! 

-304 1 table: array C 1 . .nsteps + 1 ] of complex! 
-320 1 theta tthetastep; real! 
-324 1 i: inteser! 
-324 1 listinS : text! 

b e 3 i n 

theta := 0.0! 

thetastep := pi/(2*nsteps ) ! 
a := zero! b := zero! 
for i := 1 to nsteps+1 do 

2 beSin 

2 a. re := sin(theta)! (*leaue im part zero*) 
2 b.im := cos(theta)! (*leaue re part zero*) 
2 tabled] := add(a >b) ! 
2 theta := theta + thetastep! 
2 end! 

1 uritelndistinsf t' REAL '. 
1 ' IMAGINARY ' . 

1 ' MAGNITUDE ')! 

1 for i := 1 to nsteps+1 do 

2 writeln ( listini > ' ' > 

2 tabled] . re » ' ' itableE i] . im i ' 't 

2 maiUabled]) )! 



1 end. 



No errors. 
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REAL IMAGINARY MAGNITUDE 

0.00000E+000 1.00000E+000 1.00000E+000 

9.B0171E-002 9.95185E-001 1 . OOOOOE+000 

1.95090E-001 9.B0785E-001 1. 00000E+000 

2.90285E-001 9.56940E-001 1. 00000E+000 

3.B2SB3E-001 9 . 238B.0E-001 1. OOOOOE + 000 

4.71397E-001 B.B1921E-001 1. OOOOOE+000 

5.55570E-001 B.31470E-001 1. OOOOOE+000 

B.34393E-001 7.73010E-001 1. OOOOOE+000 

7.07107E-001 7.07107E-001 1. OOOOOE+000 

7.73010E-001 B.34393E-001 1, OOOOOE+000 

8.31470E-001 5.55570E-001 1. OOOOOE+000 

8.81921E-001 4.71397E-001 1. OOOOOE+000 

9.23B80E-001 3.82683E-001 1. OOOOOE+000 

9.5B940E-001 2.90285E-001 1. OOOOOE+000 

9.80785E-001 1.95090E-001 1. OOOOOE+000 

9.95185E-001 9.80171E-002 1. OOOOOE + 000 

1. OOOOOE+000 -2.0510E-010 1.00000E+000 

An Illustration 

The accompanying listing shows the module "complexmath" embedded in a test program. The test 
program isn't very thorough, since it only checks the constant "zero" and the "add" and "mag" 
functions. 

Modules embedded in a program may be intermixed with global constant, type, and variable 
declarations, but all modules must appear before any of the program's global procedures and 
functions. Usually all the modules are put first, followed by the program's own globals. If there are 
several modules, they must be ordered so that no module is imported by another (or by the 
program) until it has been declared. 

Notice the semicolon following the END of the module (line 56), and that the program must have 
an IMPORT declaration (line 61) even though the module is physically present in the program. 

Program "ex" can be compiled and run as shown. If you'd like to try it, invoke the Compiler by 
pressing ( C ) at the Main Command Level. When asked what text to compile, put the disc 
labelled DOC: in a drive and answer: 



D0C:CX (ENTER) 
Let the Compiler put the output file on the same disc (accept the default output file). 

Compiling a Module Separately 

The file generated by compiling CX.TEXT is a library with two modules, the main program "ex" 
and module "complexmath". Strictly speaking a program isn't a module, but within a library it has 
a directory entry just as if it were. You might wish to use the Librarian and see this for yourself. The 
Librarian can display every detail of a code file. Had there been several modules in "ex", each one 
would have had a separate directory entry. 

It's important to be clear about the distinction between modules and libraries. A library is a file that 
contains object-code module(s); it is created by the Compiler or Assembler or Librarian. The 
library's name is its file name, which you can see with the Filer. Inside the library is a directory 
naming all the modules in that file. The library directory can only be displayed by the Librarian. 
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If you were satisfied at this point with the testing of "complexmath", you could use the Librarian to 
pull that one module out of the code file, and make it a user library or add it to the system library. 
The Librarian chapter describes how to do this. 

Another alternative is to compile the module separately. Simply use the Editor to create a text file 
having only the module. Notice that when the module is compiled alone, it must be terminated by a 
period instead of a semicolon. The Compiler will also accept a sequence of several modules 
separated by semicolons, as long as the last one is terminated with a period. The program listing on 
the next page shows the listing generated by a separate compilation. 

How the Compiler Finds Library Modules 

A module which has been compiled is called a "library module". Library modules can be imported 
by programs or other modules, because the compiled code file carries with it a description of the 
module's interface. The Compiler is able to read this description and from it determine how to 
properly access everything exported by the module. (Note that modules which have been "Link- 
ed" by the Librarian do not contain the module interface descriptions.) 

When the Compiler processes an IMPORT declaration, it must find the modules named in the 
import list and read their interface specifications. A particular search pattern is followed, which is 
repeated for each module named in the list. 

• If the imported module has been previously declared or imported in the source text being 
compiled, the reference is to that module. 

• If no module of that name has been found, the Compiler must search library files on mass 
storage. The file(s) to be searched may be specified in a *SEARCH 'FileName'% option. 

• If there is no $SEARCH$ option or the module is not found in the specified list of files, the 
Compiler goes on to look in the current system library. 

• If the module still isn't found, error 104 (undeclared identifier) is issued. 



Note 

The Compiler does not search libraries which have been loaded into 
memory with the P-load command. Module interface specifications are 
not retained with memory-resident libraries. 

A module which is imported may itself import other modules, which are listed in its import section. 
The Compiler must follow such a chain all the way back to its root, to a module which imports no 
others. The search pattern just described is applied recursively, to a maximum depth of ten levels. 
For a restriction, see the subsequent "INCLUDE Files" section. Sometimes in following an import 
chain, a module is named in more than one import list. The Compiler actually reads the interface 
specification for a module just once. 

If a program imports module "A", which in turn imports module "B", the things exported from 
"B" are nevertheless hidden from the program. To make them visible, "B" must also be imported 
into the program. 
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The listing below shows program "ex" recompiled to search for module "complexmath" in a 
library called "CXMODULE" on mass storage unit #3. The second listing shows "ex" recompiled 
assuming "complexmath" has been put into the current System Library. 



Pascal [Rev 2.0 10/19/82] CX.TEXT 



19-0ct-82 09:30:34 PaSe 1 



3 

a 

5 
B 
7 
B 
9 
10 
11 
12 
13 
14 
15 
IB 
17 
IB 
19 
20 
21 
22 
23 
24 
25 
2B 
27 
29 
29 
30 
31 
32 
33 
34 



-32 
-304 
-320 
-324 
-324 



program ex (listinS)i 

Ssearch '*3 : CXMDDULE ' $ 
import complexmath i 

const 

pi = 3.141592B54! 

n steps = IB! 
u a r 

a » b : complex! 

table: array [l..nsteps+l] of complex! 

t he ta i the t as tep : real! 

i : integer! 

listins : text! 



be 3 
t 
t 
a 
f 



2 

1 u 

1 

1 

1 f 

2 
2 
1 end 



l n 

h e t a : = 0.0! 

hetastep := pi / ( 2*ns t eps ) ! 

: = zero! b := zero! 
or i := 1 to nsteps+1 do 
be sin 

a. re := sin(theta)! ( * 1 e a v e 
b.im := cos(theta)! (*leaue 
t ab 1 e C i ] : = ad d ( a tb ) ! 
theta := theta + thetastep! 
end ! 
ritelnf listins . ' REAL ' i 
IMAGINARY '. 
MAGNITUDE ' ) ! 
or i : = 1 to nsteps+1 do 
writelnflistinSt' ' i 

t ab 1 e [ i ] . re i ' ' 1 1 ab 1 e [ i 1 , im ; 
in a i ( t a b 1 e C i ] ) ) i 



im part zero*) 
re part ze ro* ) 



No errorsi 
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Pascal CReu 2.0 10/19/82] CX2.TEXT 



19-0ct-BZ 09:06:14 PaSe 1 



1 : 

2: 

3: 

4; 

5: 

G: 

7: 

8: 

9: 

10: 

11 : 

12: 

13: 

14: 

15; 

IB: 

17: 

18: 

19: 

20 

21 

i. *L i 

23 
24 
25 
28 
27 
28 
29 
30 
31 
32 
33 



-32 
-304 
-320 
-324 
-324 



proSram ex (listing); 

1 import complexmathi (* from system library * ) 



const 

Pi = 3.141592B54! 

nsteps = IB! 
y a r 

aib: compl ex i 

table: array [ 1 . .nsteps + 13 of complex! 

theta tthetastep : real! 

i : integer! 

listing : text! 



be sin 

theta : = 0.0! 

thetastep := pi /( 2*n steps ) ! 
a := zero! b := zero! 
for i := 1 to nsteps+1 do 
b e $ i n 

a. re := sin(theta)! (*leaue im 
b.im := cos(theta)! (*leaye re 
tabled ] := add(aib)! 
theta := theta + thetastep! 
end ! 
writelntlistinSi' 



part ze ro*) 
part zero*) 



REAL ' . 
IMAGINARY ' . 
MAGNITUDE ')! 
for i := 1 to nsteps+1 do 
writelnflistinSi' ' > 

t ab le C i ] . re > ' ' > tab le [ i ] . im t 
maS(tableCiJ) ) ! 
end. 



No errors. No warnings. 



How the Loader Finds Library Modules 

When the Compiler processes an import declaration, it does not copy, or in any other way bind the 
library module into the program being compiled. Instead it emits reference information (called 
REF's) which enables the loader or linker to make the required connections later. Usually REF's are 
satisfied (hooked up to the library module) at the last possible moment: when you Run- the 
program. 

A compiled program contains no record of where the Compiler found any imported modules. The 
loader has a search pattern it uses to find imported things the program needs: 

• First, the file being loaded is searched. There may be modules in it which were compiled at the 
same time as the program. 

• Then memory-resident libraries are searched. The memory-resident libraries are those you 
have loaded with the P command, the contents of INITLIB (which is automatically loaded at 
boot time), and the modules of the Operating System itself. The order of search is most- 
recently-loaded first. 

• Finally, the current System Library is searched. If a required module is in the System Library, 
then it will be loaded with the program and will remain in memory until a different program is 
executed. 

• If there are still unresolved references, the loader reports them on the CRT. The program won't 
run. Control is returned to the Main Command Level. 
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If your program only imports from the System Library, everything is taken care of automatically. 
This is the most common case. If the program imports from user libraries via the $SEARCH$ 
option, you must help out the loader in one of three ways.: 

• Use the P-load command to load copies of the libraries into memory before running the 
program. Do this just once, because the loader does not check to see if modules have already 
been loaded! Memory-resident libraries stay there until you re-boot. 

• Use the Librarian to make a new library containing the compiled program and any modules it 
needs. This new library is an unlinked, executable program. It will automatically be linked 
when it is loaded. 

1 Use the Librarian to link the necessary modules to the program. The resulting library is a 
linked, executable program. It will probably still have some unresolved references (for instance 
to the system read and write routines), which will be resolved at load time. 



• 



A Subtle Point 

The loader doesn't search for modules, it searches for external names. Each procedure or function 
exported has an external name, as do most structured constants. A single name is used for all the 
variables a module exports; it is actually the name of a place in memory where storage for the 
variables will be allocated. Certain things, such as types and simple constants, are only useful at 
compile time and so have no external name. 

If two modules which are loaded define the same load-time name, the most recently loaded copy 
overrides the older one. Generally this makes no difference, because external names created by the 
Compiler identify the module where the name originated. However, some module names are used 
by the Operating System. You should avoid using these names from your own modules unless you 
intend to override the name of a system entry point. These names are listed in the Technical 
Reference Appendix. 

$INCLUDE Files 

The source text of a module or program can be broken up into several text files which are edited 
separately but compiled as a group. The $INCLUDE option tells the Compiler to insert the Pascal 
source of another file into the one it is presently compiling. 

program showinclude (input toutput) 5 
* in elude 'MYMOL : DECLARS '$ 
$ i n c 1 ud e ' SYSVOL : BODY ' $ 
end ♦ 

If the required volume is not on-line when needed, the Compiler pauses and prompts you to insert 
the proper volume. 

Miscellaneous 

• An included file may in turn include another file. This "nesting" is allowed to a maximum 
depth of 10. 

• Importing a library module is a form of file inclusion, and counts against the maximum 
allowable depth of 10 while the import declaration is being processed. 

• If the imported module has an import declaration in its own interface, the Compiler will follow 
the chain and find those module interfaces too. This is another form of nested file inclusion. 
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What Can Go Wrong? 

This section discusses some problems which may occur when using the Compiler, and how to solve 
them. 

Can't Run the Compiler 

1. If the system reports, Cannot open 'CMP : COMPILER ', the volume with the Com- 
piler is not online. You may have removed the volume and not put it back or changed it 
with the What command. If the Compiler wasn't found when the system booted, you are 
expected to put the CMP: disc (which contains the Compiler) on-line. 

2. If the system reports, Cannot load 'COMPILER', either the disc medium is bad, or 
not enough memory is installed in the Computer to run the Compiler. It is desirable to 
have at least 393K bytes; the system is normally sold with at least 524K bytes. 

Errors 900 thru 908 

During compilation, three files are written by the Compiler: the code file, which is the one you want, 
and the REF and DEF files. The latter two are temporary working storage for linkage information 
which is appended to the code file if the compilation terminates normally. All three of these files are 
normally opened on the same volume (the volume to which you directed the code file). 

Each of these files is subject to three classes of error: 

• Error in opening the file. 

• Insufficient space to open the file. 

• File fills up before compilation finishes. 

An error in opening the file usually means the volume is not online. It can also indicate that the 
volume's directory is full. 

The amount of space allocated to the code file is usually half of the largest free area on the volume, 
with the potential to expand to the second half of that area if needed. If you get errors 900, 903, or 
906 you need to make more room on the volume to which the code file was directed, or use a 
different volume. 

The REF file by default is opened with 30 blocks of disk space on the same volume as the code file. 
A Compiler option at the beginning of the source program can change the size and the volume 
selected for REF. There's no simple rule which gives the "right" size for the REF file. If the file fills 
up (error 907), make it bigger in proportion to the amount of program that remained to compile 
when the error occurred. 

$REF 50$ Allocate 50 blocks 

$REF 'CHARLIE:'* Put it on volume CHARLIE 

$REF 'CHARLIE:'. REF 50$ Put it on CHARLIE and 

allocate 50 blocks 
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Exactly analogous remarks hold for the DEF file, except that its default size is 10 blocks and the 
Compiler option is $DEF$ . 

Errors When Importing Library Modules 

1. Syntax errors in the interface of an imported library module. This usually indicates that the 
library module itself tried to import some other module which was not found by the Compil- 
er's search algorithm. 

2. Errors 608, 610: Include or import nesting too deep. If module "A" imports "B", which 
imports "C" and so forth, the Compiler must follow the chain to its end. The chain can only 
be 10 imports deep. Since the same file handling mechanism is also used to process 
$INCLUDEd files, the combined limit on import and inclusion nesting is 10 deep. 

3. Error 613: Imported module does not have interface text. If the library has been linked by the 
Librarian, the interface specification has been removed. Also, a main program looks internal- 
ly like a module; but it has no interface text. 

Not Enough Memory 

If the Compiler generates error —2 (not enough memory), then there isn't enough room in 
memory to compile the program. You can watch the numbers which appear on the screen in 
square brackets as the compilation proceeds - they show approximately how much memory is left. 
There are two primary reasons for running out of memory during a. compilation: one of them is 
large procedure bodies, and the other is P-loaded files. 

Large Procedure Bodies 

When the Compiler processes a procedure, the entire procedure (declarations and body) is scan- 
ned. An internal representation of the procedure, called a "tree", is built. This tree is not complete 
until the scanner reaches the end of the procedure, and only then does code generation begin. The 
tree form takes a lot of storage, particularly the statements making up the body. If you write a 
procedure whose body is ten pages long, the Compiler is very likely to run out of memory. The 
moral is that you should keep your procedures reasonably short. A good guideline is that no 
procedure should be longer than a page or two. 

P-loaded Files 

If you've Permanent-loaded a lot of libraries or programs, or space has been allocated to a 
memory-resident mass storage volume, you can reboot the system to recover the memory, and try 
again. 

Insufficient Space for Global Variables 

You may discover, either at compile time or at run time, that there isn't sufficient space for the 
global variables of your program. If this happens, please refer to "Implementation Restrictions" in 
this chapter, which explains the limitations and what to do if you exceed them. 

Errors 403 thru 409 

These errors should never be reported. They indicate a malfunction in the Compiler itself. If this 
ever happens, please show the program which causes it to your HP field support contact. 
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Compiler Options 

Compiler options affect the code emitted by the Compiler. For instance, the $DEBUG ON$ option 
causes the Compiler to emit a TRAP instruction after the object code for each Pascal statement, 
allowing you to single-step the program. 

Sometimes there are restrictions on where an option may appear: 



Location 



Restrictions 



Anywhere 
At front 

Not in body 

Statement 
Special 



Indicates that the location of the option in the file is irrelevant. 

Applies to entire source file; must appear before the first "token" in the source 
file (before PROGRAM, or before MODULE if compiling a list of modules). 

Applies to a whole procedure or function; can't appear between BEGIN and 
END. Good practice to put these options immediately before the word BEGIN 
or the procedure heading. 

Can be applied on a statement-by-statement basis or to a group of statements, 
by enabling before and disabling after the statement(s) of interest. 

As explained under the particular option. 



If an option appears in the interface (import or export) part of a module, it will have effect as the 
module is compiled. However, the option itself will not become part of the interface specification in 
the compiled module's object code. 
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ALIAS 



Default: External name = Procedure Name 
Location: Special, See Below 

This Compiler option causes a name, other than the name used in the Pascal procedure or function 
declaration, to be used by the loader. 



-»-($)-» { alias ) -»{ 7 )-»H~ 



Item 


Description/Default 


Range Restrictions 


external name 


string 


lto80 

ASCII Characters 



Semantics 

The string parameter specifies the external name for the procedure in whose header the option 
appears. 

Example: 

procedure * a 1 i a s 'charlie'$ p (i: integer) i external? 

Within the program, calls use the name "p"; but the loader will link to a physical routine called 
"charlie". 



Should appear between the keywords PROCEDURE or FUNCTION and the routine's identi- 
fier. 
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ALLOWJPACKED 



Default: OFF 
Location: Anywhere 



This option permits or prohibits the passing of elements of packed arrays or records to v a r para- 
meters. 

Semantics 

"ALLOW_PACKED" is interpreted as "ALLOW_PACKED ON". 

Passing elements of packed arrays or records to VAR parameters is illegal in HP Standard Pascal, 
but the Workstation Pascal Compilers prior to Version 3.1 allowed it. Pascal 3.1 and sub- 
sequent compilers allow passing of packed elements to uar parameters only if the compiler option 
ALLOW_PACKED is ON. 

ON specifies that elements of packed structures will be allowed to be passed to v a r parameters in 
functions and procedures. You may need to add the option $ALLOW_PACKED ON$ and re- 
compile existing pre-3.1 Pascal source code to run it on the 3.1 system. 

OFF specifies that passing elements of packed structures to u a r parameters is illegal. Attempts to do 
so result in a compile-time error message 154: "Illegal argument to match pass-by-reference 
parameter". 



Note 

Pre-3.1 compilers allowed only certain packed elements to be passed to 
war parameters. These are the elements which ALLOW_PACKED 
affects. Others, which pre-3. 1 compilers forbade from being passed, are 
still forbidden in 3. 1 and later compilers. 
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ANSI 



Default: OFF 
Location: At Front 

This Compiler option selects whether an error message is to be emitted for use of any feature of HP 
Standard Pascal not contained in ANSI/ISO Standard Pascal. 



— *"\$)~~*"\ ansi j — r~*~\ 0N ) — p*"vO — *" 



m: 



OFF 



Semantics 

"ANSI" is interpreted as "ANSI ON". 

ON causes error messages to be issued for use of any feature of HP Standard Pascal which is not 
part of ANSI/ISO Standard Pascal. 

OFF suppresses the error messages. 

Example: 

$ans i on$ 
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CALLABS 



Default: ON 
Location: Statement 

This Compiler option determines whether 16-bit relative or 32 -bit absolute jumps are to be gener- 
ated by the Compiler. 



— «-/$\-^CALLABSJ [-»- ( ON J T~*~\*) *" 

w ( off y~J 



Semantics 

"CALLABS" is interpreted as "CALLABS ON". 

ON specifies that 32-bit absolute jumps will be emitted for all forward and external procedure calls. 
OFF specifies 16-bit PC-relative jumps. 
Allowed on a statement-by-statement basis. 

Example: 

$callabs off* 
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CODE 

Default: ON 
Location: Not in Body 

This Compiler option is used to control whether a CODE file will be generated by the Compiler. 
~~ *"yO~~*"C C0DE J — Tv 0N J — I~*vO — *~ 



k: 



OFF 



Semantics 

"CODE" is interpreted as "CODE ON". 
ON specifies that a code file will be generated. 

Example: 

$code off* 
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CODE_OFFSETS 



Default: OFF 
Location: Not in Body 



This Compiler option controls the inclusion of program counter offsets in the compiler listing. 

— *-/$\-»-{cODE..OFFSETs) r*"T 0N J I~*"vO — *" 



K 



OFF 



Semantics 

"CODE_OFFSETS" is interpreted as "CODE_OFFSETS ON". 

ON specifies that line-number/program-counter pairs will be printed for each executable statement 
listed. This can be applied on a procedure-by-procedure basis. 
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COPYRIGHT 



Default: Not Applicable 
Location: Anywhere 



This Compiler option is provided for inclusion of copyright information. 
— *-^$ j— *-TcopyrightV- «-T ' J—*- 



Item 


Description/Default 


Range Restrictions 


copyright 
message 


string 


lto80 

ASCII Characters 



Semantics 

The string parameter is placed in the object file as the owner of the copyright. If more than one 
COPYRIGHT option is included, the last one is effective. 

Example: 

$copyri3ht 'Hewlett Packard Company i 1381'$ 
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DEBUG 



Default: OFF 
Location: Not in Body 

This Compiler option controls whether the code produced by the Compiler contains the additional 
information necessary for full use of the Debugger system. 



--($)-»»^ DEBUG ) — [-»- ( on ) — T~\*)~ *~ 






Semantics 

"DEBUG" is interpreted as "DEBUG ON" 

"DEBUG ON" will cause debugging instructions to be emitted for the procedure bodies following 
it. May be applied on a procedure-by-procedure basis. 

Example: 

procedure buSdy 5 

Mar i: integer! 

$ d e b u 9 on$ 

b e 9 i n 

• ♦ ♦ 

end 5 

$debusr off$ 
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DEF 



Default: 10 records on same volume as code output 
Location: At Front 

This Compiler option allows the user to change the size and location of the temporary Compiler file 
named ".DEF". 



~*k^)~ *~ c ° ef y ~ 



def file 
size 



HIH 



def file 
volume id 




■0- 



Item 


Description/Default 


Range Restrictions 


def file size 


integer constant 


less than 32767 


def file 
volume id 


string 


valid volume id (see 
glossary) 



Semantics 

If the parameter is a string, it specifies the volume where a temporary Compiler file called ".DEF", 
which holds external definitions, will be stored. If the parameter is a number, it specifies how many 
logical records will be allocated for the DEF file. See "What Can Go Wrong, Errors 900 to 908". 

Examples: 

$def 50$ 

$def ' Junkuol : '$ 

$def ' Junkuol : ' f def 50$ 
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FLOAT_HDW 



Default: OFF 
Location: Not in body 

This option enables and disables the use of floating-point hardware. 



c™y~ rKD— »• 




Semantics 

HP 98635 Floating-point Math Card 

The HP 98635 is an optional PC board that increases the execution speed of floating-point math 
computations. This board can be installed in all Series 200 computers. 

• ON instructs COMPILER to generate accesses to 98635 hardware for the floating-point opera- 
tions listed below. If the hardware is not installed when the program is executed, an error will 
be reported. 

• OFF tells COMPILER to generate math library calls for floating-point operations. 

• TEST causes COMPILER to generate both hardware accesses and library calls. The code 
includes tests for the presence of floating-point hardware. If the test succeeds (at execution 
time), the hardware accesses are used; otherwise, the library calls are used. 

Operations that can potentially use the 98635 floating-point card include: addition, subtraction, 
multiplication, division, negation, and the sq r function. Hardware can also be used by any opera- 
tion that converts an integer into a real or longreal; however, hardware is not used by operations 
that convert reals or longreals into integers. All other math functions call library routines. There are 
also libraries that access the floating-point hardware. 

MC6888 1 Floating-point Math Co-processor 

When using this option with the COMPILE20 compiler on Series 300 computers equipped with the 
optional MC6888 1 math co-processor, this Compiler option has slightly different meaning. 

• ON causes COMPILE20 to generate MC6888 1 co-processor instructions. 

• OFF causes COMPILE20 to generate code that uses Pascal math libraries. 

• TEST is not allowed (COMPILE20 reports an error). 

Operations that can can potentially use the 68881 hardware include all floating-point math com- 
putations except t rune. 
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HEAP_DISPOSE 



Default: OFF 
Location: At Front 



This Compiler option enables and disables "garbage collection" in the heap. 
~~ *"\$V"*"\ HEAP - D,SP0SE J — r~**\ 0N ) — r~*""C$~) — *~ 



K 



OFF 



Semantics 

"HEAPJDISPOSE" is interpreted as "HEAP_DISPOSE ON" 

ON indicates that DISPOSE allows disposed objects to be reused. 

OFF does not recycle disposed objects. If enabled, this option must appear at the front of the main 
program. 

Example: 

*heap_d ispose on$ 
program recycle! 
• • ♦ 
be Sin 

dispose(p)! (*f ree up cell*) 

new(p)5 (*probably Sets same cell back*) 
end ♦ 

The HEAP-DISPOSE option must be the same (either ON or OFF) in the program and all modules 
imported by the program. Erroneous results may occur if those declarations don't agree, because 
there is no way for the Compiler to check on which option other modules have used. 
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IF 



Default: Not Applicable 
Location: Anywhere 

This Compiler option allows conditional compilation. 



Item 



boolean 
expression 



conditional 
text 



Description/Default 



expression that evaluates to either TRUE or FALSE 



source to be conditionally 
compiled 



Restrictions 



may only contain 
compile time constants 



If the expression evaluates to FALSE, then text following the option is skipped up to the next 
$END$ option. 

If the boolean expression evaluates to TRUE, then the text following the option is compiled 
normally. 

IF-END option blocks may not be nested. 

String constants may not be used. 

Example: 

const fancy = true! 
limit = 105 
size = 9 5 
♦ » ♦ 
$if fancy and (<size+l)<limit)$ 

,,, (* this will be skipped *) 
$end$ 
« ♦ « 

$if FALSE* 

...(* this will also be skipped*) 
*end$ 
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INCLUDE 



Default: Not Applicable 
Location: Anywhere 

This Compiler option allows text from another file to be included in the compilation process. 

-K^- K^^^ HrO- H sprier h HTQ-<$>H 



Item 



file specifier 



Description/Default 



string 



Range 
Restrictions 



any valid file specifier 
(see Glossary) 



The string parameter names a file which contains Pascal source to be included at the current 
position in the program. Included code may contain additional INCLUDE options (nesting level is 
10). The remainder of the line which contains this option must be blank except for the closing $. 

Example: 

p ro 3 ram inclusive! 
♦include 'souroerdeclars'* 
♦ include ' s o u r c e : b o d v ' $ 
end . 
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IOCHECK 



Default: ON 
Location: Statement 



This Compiler option enables and disables error checking following calls to system I/O routines. 
— *-^$\->-r iocheck J — p-»^oN j — T"v?y — *"" 




OFF 



Semantics 

"IOCHECK" is interpreted as "IOCHECK ON" 

ON specifies that error checks will be emitted following calls on system I/O routines such as RESET, 
REWRITE, READ, WRITE. Can be used in conjunction with the standard function IORESULT if 
UCSD or SYSPROG language features have been enabled. Allowed on a statement-by-statement 
basis. 

OFF specifies that no error will be reported in case of failure. 

Example: 

$ucsd$ 

4*4 

$iochecK off* 

reset <f > 'dataf ile ' > 5 

tiochecK on* 

if ioresult <> then w r i t e 1 n < ' I D error')? 
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LINENUM 



Default: Not Applicable 
Location: Anywhere 



This Compiler option allows the user to establish an arbitrary line number value. 
~~ \^/~\. LINENUM j—*" 



line number 



h®- 



Item 


Description/Default 


Range Restrictions 


line number 


integer numeric constant 


0.. 65535 



Semantics 

The integer parameter becomes the current line number (for listing and debugging purposes). 

Example: 

$linenuffl 20000$ 
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LINES 



Default: 60 lines per page 
Location: Anywhere 

This Compiler option allows the user to specify the number of lines-per-page on the Compiler 
listing. 2000000 lines-per-page suppresses autopagination. 



-*($)-» < unes y * \ %y H Jy+ 



Item 


Description/Default 


Range Restrictions 


lines per page 


integer numeric constant 


20 thru MAXINT 



Example: 



$1 ines 55$ 

$lines 2000000$ ( *supp ress aut op'asfinat i on* ) 
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LIST 



Default: ON to PRINTER: 
Location: Anywhere 

This Compiler option controls whether or not a listing is being generated, and to where it will be 
directed. 



-(H^>t(H^K>t>(»- 






Item 


Description/Default 


Range Restrictions 


file specifier 


string 


any valid file specifier 
(see glossary) 



Semantics 

"LIST" is interpreted as "LIST ON". 

LIST with a file specifier specifies that the file is to receive the compilation listing. 

LIST OFF suppresses listing. 

LIST ON resumes listing. No listing will be produced at all, regardless of this option, unless 
requested by the operator when the Compiler is invoked. 

Examples: 

$list 'my uol : Keepl i st . text '* 

$1 i st 'printer: '$ 

$list off* 
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OVFLCHECK 

Default: ON 

Location: Statement-by-statement 

This Compiler option gives the user some control over overflow checks on arithmetic operations. 
— ^T$\-»-/ovflcheck) — r~*"\ 0N J — ITvO — "*" 



h: 



OFF 



Semantics 

"OVFLCHECK" is interpreted as "OVFLCHECK ON" 

ON specifies that overflow checks will be emitted for all in-line arithmetic operations. 

OFF does not suppress all checks; they will still be made for 32-bit integer DIV, MOD, and 
multiplication. 

Example: 

$ouflcheck a f f $ 
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PAGE 

Default: Not Applicable 
Location; Anywhere 

This Compiler option causes a formfeed to be sent to the listing file if compilation listing is enabled. 

— ^y)-»-( pAGEj -*»{T)— *- 

Example: 
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PAGEWIDTH 



Default: 120 
Location: Anywhere 

This Compiler option allows the user to specify the width of the compilation listing. 



— *-T$J— *-^pagewidthV-»- 



Item 


Description/Default 


Range Restrictions 


characters per 
line 


integer numeric constant 


80 thru 132 



Semantics 

The integer parameter specifies the number of characters in a printer line. 

Example: 

$pa«(ewidth 80$ 
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PARTIAL_EVAL 



Default: OFF 

Location: Statement-by-statement 



— »>/$)— »-fpARTIAL_EVALj [~~*"\ 0N ) T~*"\^) — *" 



K 



OFF 



Semantics 

"PARTIAL_EVAL" is interpreted as "PARTIAL_EVAL ON". 

ON suppresses the evaluation of the right operand of the AND operator when the left operand 
is FALSE. The right operand will not be evaluated for OR if the left operand is TRUE. 

OFF causes all operands in logical operations to be evaluated regardless of the condition of any 
other operands. 

Example: 

$pa rt i a l_eu al on* 

while (pOnil) and ( p" ♦ count >0 ) do 
p : = p '"' . 1 i n k 5 
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RANGE 



Default: ON 

Location: Statement-by-statement 



This Compiler option enables and disables run-time-checks for range errors. 
—*\i)—*\ r*nge j I » T on j — r"*"v $) — *~ 






Semantics 

"RANGE" is interpreted as "RANGE ON". 

ON specifies that run time checks will be emitted for array and case indexing, subrange assign- 
ment, and pointer dereferencing. 

Example: 

Mar a: array[1..10] of integer? 
i: inteserS 

• ♦ ♦ 

i := 115 

$ranse off* 

aCil := 0! <# invalid index not causht!*) 
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REF 



Default: 30 records on same volume as code output 
Location: At Front 

This Compiler option allows the user to change the size and location of the temporary Compiler file 
named ".REF". 



-»-{T)-»" ( REF ) - 



ref file 
size 



^H 



ref file 
volume id 




<i>~ 



Item 


Description/Default 


Range Restrictions 


ref file size 


integer numeric constant 


less than 32767 


ref file 


string 


valid volume id (see 


volume id 




glossary) 



Semantics 

If the parameter is a string, it specifies the volume where a temporary Compiler file called 
".REF", which holds external references, will be stored. If the parameter is a number, it 
specifies how many logical records will be allocated for the REF file. See "What Can Go Wrong, 
Errors 900 to 908". 



Examples: 



$ref 20$ 

$ref 'JUNK VOL: '$ 

$ref 'JUNK VOL: ' , ref 50$ 
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SAVE_CONST 



Default: ON 
Location: Anywhere 

This Compiler option controls whether the name of a structured constant may be used by other 
structured constants. 



-*-/$\-»>/save_const) — r~»*\ 0N J — ITvA) — **" 



K 



OFF 



Semantics 

"SAVE_CONST" is interpreted as "SAVE_CONST ON". 

ON specifies that compile-time storage for the value of each structured constant will be retained 
for the scope of the constant's name (so that other structured constants may use the name). 

OFF specifies that storage will be deallocated after code is generated for the structured con- 
stant. 

Example: 

$saue_const off* 

type ary = array Ci*. 100] of integer! 

const aeon = ary C345»45G91> 3 5 

<*bi«f constants taKe lots of compile-time 
m e m o r y * ) 
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SEARCH 



Default: Not Applicable 
Location: Anywhere 

This Compiler option is used to specify files to be used to satisfy IMPORT declarations. 



1 



O 



-h^-K^'hV-Ma H *S* h K 7 )— *-<*)— 



L 



Item 


Description/Default 


Range Restrictions 


file specifier 


string 


any valid file specifier 
(see Glossary) 



Semantics 

Each string specifies a file which may be used to satisfy IMPORT declarations. Files will be 
searched in the order given. The current system library is always searched last. A maximum of 9 
files may be listed. 

Multiple SEARCH options are allowed; for instance, you may want to use one for each import 
declaration. Note that only the last one encountered during compilation will be in effect for any 
import statement (i.e., these options are not cumulative). 

Example: 

$search 'FIRSTFILE' > 'SECDNDFILE '$ 
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SEARCFLSIZE 



Default: 10 files 
Location: At front 

This Compiler option allows you to increase the number of external files you may SEARCH 
during a module's compilation. 



— -0 — <search_size) — 4IE2SZ1 — *(D 



Item 


Description/Default 


Range 
Restrictions 


number of files 


integer numeric constant 


less than 32767 



Semantics 

When compiling a Pascal module, it is sometimes desirable to import another module from 
another file. To import a module from another file, the SEARCH option is used to identify the 
file. Up to ten SEARCH options may be given unless the SEARCH_SIZE options is given. The 
SEARCH_SIZE option allows you to SEARCH up to 32,766 external files for imported mod- 
ules. 



Example: 



$sea rch_s i ze 30$ 
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STACKCHECK 



Default: ON 
Location: Not in Body 



This Compiler option enables and disables stack overflow checks. 

—*-($)—*-( STACKCHECK J r~*"\ 0N ) T~*"0) — *~ 



k: 



OFF 



Semantics 

"STACKCHECK" is interpreted as "STACKCHECK ON". 

ON specifies that stack overflow checks will be generated at procedure entry. It is very danger- 
ous to turn overflow checks off! Obscure and unreported errors may result. 

Example: 

tstaokohecK off* 
procedure unsafe? 
v a r 

m a ■/ _ s m a s h _ h e a p : array C 1 . . 5 3 of integer! 
b e at i n . » . end? 
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SWITCH_STRPOS 



Default: Off 
Location: At front 



This Compiler option reverses the positions of the parameters of the STRPOS function. 



SWITCH_STRP0S 

Semantics 

When this Compiler option is used, the exprected order of the parameters is that of the HP 
standard. In Series 200 Pascal (like UCSD's POS function), the STRPOS function expects the 
first string parameter to be the search pattern and the second string parameter to be the source 
string in which the search takes place. Later the HP standard was established with the order of 
the parameters reversed. If $WARN OFF$ is not in effect, then the Compiler issues a harmless 
warning that you are not conforming to the standard. If you wish to conform to the standard, 
give the SWITCH_STRPOS option in your program. 

Example: 

tswitch.strpos* 
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SYSPROG 



Default: System Programming Extensions not enabled 
Location: At Front 

This Compiler option makes available some language extensions which are useful in systems 
programming applications. See "System Programming Language Features" in this chapter. 

~*\!w~ *""C s YSPR0G v~~ \f) — *~ 

Semantics 

$SYSPROG$ is interpreted as $SYSPROG ON$ 

Example: 

$sy sp ro £f$ 

p r o 3 r a m machinedependent! 
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TABLES 



Default: OFF 
Location: Not in Body 



This Compiler option allows the user to turn on and off the listing of symbol tables. 

— ^\$V*-\ TABLES J r~*"V ° N J 1 * (jU~*~ 






Semantics 

"TABLES" is interpreted as "TABLES ON" 

ON specifies that symbol table information will be printed following the listing of each proce- 
dure. This is useful for very low-level debugging. 

Example: 

$tables* 

procedure hasabuJ ( u a r p: integer)! 

i.i a r 
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UCSD 



Default: UCSD not enabled 
Location: At Front 

This Compiler option allows the compiler to accept most UCSD Pascal language extensions. 
See the subsequent "Converting UCSD Pascal" section later in this chapter. 



— -{$)-»» ( ucsd y -*^$y— »- 



Example: 

$ u c s d $ 

program f u n n y i o 5 

ua r 

f: file! < * no type specified! *) 

b e S i ri 

Lin i t read ( 8 »a ry »80 1 10 ) 5 
end . 
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WARN 



Default: ON 
Location: At Front 



This option allows the user to suppress the generation of compiler warning messages. 

-**{*)-"*" {! warn ) — r** ^ 0N ) — r*"® - •" 



OFF 



Semantics 

"Warn" is interpreted as "WARN ON" and compiler warnings will be issued. 

Example 

$warn off$ 
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How Pascal Programs Use the Stack 

This section describes how Pascal programs use the stack to store data, return addresses for 
procedures, and pointers needed to access variables belonging to nested procedures. The 
information can be useful when writing assembly language routines, and when debugging at 
the machine level. 

You can also investigate this subject by writing some Pascal test programs and then looking at the 
emitted code with the Librarian's Unassemble command. Two Compiler options also produce 
valuable information: $DEBUG ON$ correlates the machine code displayed by Unassemble with 
the original Pascal lines, and $TABLES$ causes the Compiler to print a description of the size and 
location of each object in the program. 

The Pascal Stack 

Five types of data can be stored on the stack: 

• procedure/function parameters 

• return addresses 

• local variables 

• stack frame pointers 

• static links 

Two address registers are reserved for stack manipulations: 

• A7 - the stack pointer (SP) 

• A6 - the stack frame pointer (SF) 

The stack grows downward in memory as procedures are called, with A7 always pointing to the 
base (beginning, lowest address) of the datum on the "top" of the stack. That is, when space is 
allocated for a procedure which has been called, the area allocated has a lower (more negative) 
address than the space already allocated for the calling procedure. Space allocated to a proce- 
dure is called its stack frame. 

However, variables extend upward in memory. This simply means that the address of the first 
element of an array, or the first field of a record, is lower than the address of the second element 
or field. 

Global Variables 

Register A5 is reserved as the global base register. A reference to any program or module global 
variable is always formulated as a displacement from where register A5 points. The maximum size 
of the global area is 65 536 bytes (the displacement field size). In practice, not all of this space is 
available to the program. Some of this area is used for system globals, command interpreter 
globals, permanently loaded programs and modules, and so forth. 

See the Assembler chapter for details on how to reference Pascal global variables from assem- 
bly language programs. 
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Procedure Calls 

When one procedure calls another, the caller pushes any parameters to the called procedure on 
the stack. The parameters are pushed on the stack by first decrementing the stack pointer (A7) 
an amount equal to the size of the parameter, then storing the parameter where SP now points. 
(Pushing a byte decrements the stack pointer by two, since it must always have an even value. ) 
The calling procedure executes a JSR instruction which pushes the return address on the stack 
and jumps to the entry point of the called procedure. 

The first instruction executed by the called procedure is a LINK instruction. The LINK instruction 
format and function is illustrated below: 

format: LINKA6,# -d 

function: A6 —* — (SP) — push the stack frame pointer onto the 

stack 
SP -» A6 — set the stack frame pointer equal to the 

stack pointer 
SP-d —*■ SP — drop the stack by the size(d) of the local 

variables for the called procedure 

If the program is compiled with $STACKCHECK ON$ (which is the default), a TRAP instruction is 
issued instead of LINK. The trap service routine checks for stack overflow as it adjusts A6 and SP. In 
this case the size #d is stored in the next word after the TRAP instruction. 

The stack frame pointer (A6) is used by the called procedure to reference its local variables. See 
Figure 6 for an illustration of stack usage for level 1 procedure calls. Level 1 procedures are 
those declared at the global level of a program or module. 

If the called procedure is not at level 1, the calling procedure pushes a pointer to the stack frame 
of the procedure in which the called procedure is declared. This pointer is called the static link. 
It is used by the called procedure to resolve references to intermediate variables — variables 
which are neither local to the called procedure, nor globals of the program. 

An example might help to clarify the static link. Consider the following program structure 
(indentation indicates nesting): 

p r o 3 r a rt i main 
procedure p1 

procedure p2 
procedure p3 
procedure p4 

Assume this calling sequence: main calls pi, calls p2, calls p4. If p4 calls p3 then the static link 
pushed would be that of procedure p2 (since p4 is declared within p2). If instead p4 were to call 
p2 then the static link would point to pi (p2 is nested within pi). See Figure 7 for a detailed 
example of static links. 
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The called procedure is responsible for stack cleanup and for effecting the return to the calling 
procedure. Any parameters, local data, or static links belonging to the called procedure must be 
removed from the stack before returning to the caller. Once this is complete a return to the 
calling procedure can be performed. 

The stack cleanup is performed in two steps: 

Step 1: Restore the stack frame pointer. Use the UNLK instruction to remove local data from 
the stack. 

format: UNLK A6 

function: A6—»SP — set the stack equal to the stack frame 

pointer 
(SP) H — * A6 — load the stack frame pointer from the 

stack and autoincrement the stack 
pointer (this leaves the stack pointer 
pointing to the return address) 

Step 2: Restore the stack pointer. This removes the static link and parameters from the stack. 
After this step, the stack pointer should be as it was before the procedure call. 

The called procedure returns to the caller by branching to the return address. If the return 
address was saved in an address register during stack cleanup then an indirect JMP through the 
address register is executed. If the return address was left on the stack then an RTS instruction is 
executed. 

format: RTS 

function: (SP)H — » PC — set the program counter to the value 

pointed to by the stack pointer and 
pop the value off the stack 

See Figure 8 for an example of a return from a called procedure. 

Function Calls 

Function calls differ from procedure calls only in that they return results. The result is usually 
returned on the stack. It is the responsibility of the calling procedure or function to pop the 
result off of the stack. This is normally done when the result is referenced. 

Parameter Passing Mechanisms 

There are two kinds of formal parameters: those passed by reference, and those passed by value. 

• reference parameters 

all handled alike 

• value parameters: 

a) simple value parameters: 
simple types (integer, char. ) 

array and record types < = 4 bytes 

b) copied value parameters: 

reals, and array and record types > 4 bytes 
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Reference parameters are those which are specified VAR in the procedure heading. They are 
"passed by reference": the address of the actual parameter is passed to the called procedure or 
function. This address is used for all references to the parameter. No copying of the parameter 
is performed. 

Value parameters are those which are not specified VAR in the heading. They are "passed by 
value": a copy of the parameter is passed to the called procedure or function. If the value para- 
meter is a simple type (except REAL), then its value is pushed on the stack. If the parameter is a 
simple REAL, or an array or record (and its size is more than 4 bytes), then its address is pushed on 
the stack by the caller. Before the called routine executes its first statement, it uses the pushed 
address to copy the parameter into its local data space (the Compiler reserved this space in addition 
to the local variable space). 

Values of type "procedure" are not copied; their values are pushed directly even though they 
are eight bytes long. 

Function Results 

Sometimes the calling environment must allocate temporary space in which to return function 
results. In general this is necessary when the function returns a result which is bigger than 4 
bytes. The temporary space is allocated as part of the program's global area if the call is from 
the main program; otherwise it is allocated as part of the local data area. The amount of 
temporary space required is determined at compile time. Functions which return a value of type 
real are an exception; the result area is on the stack and occupies eight bytes. 

Figure 6. PASCAL Procedure Calls (Without Static Links) 





Return Address 






A6 








Local Var_1 


I 






h 




Local Var n 


) 




Parm_1 








•— 




Parm_n 






Return Address 






* 


A6 -► 


A6 










Local Var_1 










•— 


A7 — 


Local Var_n 


. 



local variables for calling procedure 



parameters for called procedure 



return address pushed on the stack by the jsr 
instruction executed by the calling procedure 

the stack frame pointer pushed on the stack by 
the link instruction executed by the called pro- 
cedure 

local variables for called procedure 



(The stack is pictured growing toward the bottom of the page. Pointers actually address the bottom of the designated entry.) 
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The following Pascal program illustrates the use of the static link. 

*DEBUG 0N$ 

program main ( input ^output ) i 

var i : inte Je r i 

procedure A! 
war k : i n t e S e r i 

procedure Bi 

war m : i n t e S e r i 

procedure C( i : inteSe r) i 
var o : intese r i 

procedure D i 
war i: in tester! 
beSin 

i := Hi 

K : = ttii 

m i = o i 

o i = q i 

q := 15 

Bi 

C(i) ! 
end! {D> 

beSin iC> 

a := o i 

Di 
end! {C> 

beiin {B> 

K := li 

C<i«) i 
end! -CB> 

beSin {A> 

Bi 
end! {A} 

beSin {main} 

Ai 
end . 



Note 

The preceding program is only for the purpose of illustrating the use of 
the static link. Running the program results in error - 2 (not enough 
memory), because the program recurses infinitely. 
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Consider the following calling sequence: 

main calls A 
A calls B 

B calls C (with m as the parameter) 
C calls D 
D calls B 

The stack for this calling sequence is shown in Figure 7. 

Figure 7. PASCAL Procecure Calls With Static Links 
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Note 1: The static link and the parameters are always accessed at positive offsets from A6. The 
effective address of the static link (if present) is always 8(A6). Local variables are at 
negative displacements from A6. 

Note 2: In general the static link gives the called procedure access to the intermediate variables 
of procedures which precede it in the calling sequence. In this particular case the static 
link gives procedure B access to variables declared within procedure A. 



(Pointers actually address the bottom of the designated entry.) 
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Procedure D reaches intermediate variables using: 

• its current stack frame pointer 

• the difference between its nesting level and that of the called procedure 

In this case procedure D is at level 4 and procedure B is at level 2, for a relative distance 
of 2. Therefore procedure B must follow two static links to reach the stack frame of B. 

In other words: 

MOVEA.L 8(A6),A0 - get procedure D's static link 

MOVEA.L 8(A0),A0 - get procedure C's static link 

MOVE.L 8(A0),-(SP) - get procedure B's static link 

and push it on the stack 

Remember: procedure C's static link gives access to B's locals, 
procedure B's static link gives access to A's, etc. 

Note 3: When nested procedures reference intermediate variables they use the static link. An 
example of this is when procedure D references k and m in the statement k : = m;. 

k is declared in procedure A and m is in procedure B. The nesting level relative to 
procedure D for k is 3 and for m it is 2. 

The following code will perform the statement k : = m. 

MOVEA.L 8(A6),A0 get D's static link 

MOVEA.L 8(A0),A0 get C's static link 

MOVEA.L 8(A0),A0 get B's static link 

MOVEA.L 8(A6),al get D's static link 

MOVEA.L 8(al),al get C's static link 

MOVE.L -4(al),-4(A0) store mink 
The return to procedure A (as shown in the following stack segment) is accomplished in four 
steps. Note: the register prefixes indicate the value of the register for the indicated step. The 
values are those the registers have AFTER the step has been executed. 

Step 1: UNLK A6 - restore the stack frame pointer (A6) 

Step 2: MOVEA.L (SP) + ,A0 - save the return address in AO 

Step 3: ADDQ.l #12,SP - restore the stack pointer 

Step 4: JMP (AO) - return to where procedure A called B 
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If there are not any parameters then the return sequence normally is: 

UNLK A6 - restore the stack frame pointer 

MOVEA.L (SP) + ,(SP) - replace the static link with the return 

address 
RTS - return to procedure A 

If there is no static link (and no parameters) then the sequence is: 



UNLK A6 
RTS 



restore the stack frame pointer 
return to procedure A 



Figure 8. Return from a Procedure Call 



(Stepl) A6- 
(Step 3) A7 ■ 



(Step 2) A7 - 

(Step 1) A7- 

(Start) A6 - 

(Start) A7 - 



A6 



Local Var 



.... . 



" - r 



Static Link 



Return Address 



A6 



Local Vi' 'i 



STACK FOft PROCEDURE A 
a local variable for A 

STACK =OB PROCEDURE B 
a parameter for B 

mother parameter to? 3 

caned procedure 3*3 
accsss to A's local variables 

local variable m 



(Pointers actually address the bottom of the designated entry.) 
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The Assembler 



Chapter 



Introduction 

This chapter describes the use of the Workstation Assembler subsystem. The Assembler translates 
assembly language routines into object code which can be executed on this system. Assembly 
language programming gives you the ability to optimize critical sections of a program (such as for 
reductions in execution time or code size). 

The Workstation Assembler, which has a two-pass design, translates source files written in the 
assembly language specified by Motorola in the MC68000 1 and MC68020 manuals included in the 
Workstation Pascal documentation package. It also assembles instructions for the MC68881 float- 
ing-point math co-processor, which are described in the 68881 manual included in the Workstation 
documentation. A summary of the syntax required by this Assembler is provided in the "Instruction 
Syntax" section of this chapter. 

Although it is not a tutorial on assembly language programming, this chapter contains the informa- 
tion necessary to write and execute assembly language routines on the Workstation System. The 
first section demonstrates the method of generating external procedures and entire object modules 
of Assembler code that can be interfaced to Pascal programs. You should be familiar with the 
concept of Pascal modules before attempting to emulate them in assembly language; refer to the 
"Pascal Compiler" chapter for pertinent information. 

Unlike most other assembler subsystems you may have used, the directives ("pseudo-operations") 
that you give to the Workstation Assembler are specified within the source program - they are not 
given in an interactive session with the Assembler. The Workstation Assembler's pseudo-operations 
are fully described in the "Pseudo-op Reference" section near the end of this chapter. 



1 The MC68000 manual also includes documentation for the MC68010 processor. 
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Operating the Assembler 

This section shows you how to: 

• Invoke the Assembler 

• Specify the name of your text file program and your resulting code file 

• Give listing specifications 

• Interpret the listing 

Invoking the Assembler 

The Assembler is delivered on the ASM: disc. If you plan to run the Assembler several times in a 
session, you could use the Permanent command to kee p the Assembler in memory ready to run. 
Otherwise, put the ASM: disc in a drive and press ( A ) to run the Assembler. 

Source File Specification 

If there is a work file (see the Filer chapter), that file will be automatically assembled and there 
will be an "errors only" listing on the CRT. If the "errors only" listing is sufficient, your source 
program file can be specified as the work file. Otherwise, clear the work file. 

If there is no work file, you will be prompted to enter the name of your program file: 
What source file?_ 

Enter the volume name (unless using the default volume explained in the Filer chapter), and file 
name of your source program. It is not necessary to include the ".TEXT" suffix of your file 
name. If it is not included, it will be done for you by the system. For example, if your program 
file is called PROGRAM. TEXT and it is on the volume called TOMS:, then use this file specifica- 
tion: 

TOMS:PROGRAM 

Listing File Information 

You are then prompted to specify whether or not you will want a listing of the assembly: 

Do you want a program listing ( v / n / e ) ? _ 
You may type: 



( Y j for a complete listing 

( N } for no listing but errors reported on the CRT 

( E ) for a listing of the errors only 

If you want a listing, you can have it printed immediately or have the Assembler generate a file 
of the listing information: 

What listing file (default PRINTER: PROGRAM. ASC ) ?_ 



For a printer listing, press ( Return ) or (ENTER) . 
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To generate a listing on a file, enter the name of the volume and the name of the file. It is 
recommended that a size specification be made for the listing file (See the Filer chapter). 
Otherwise, the largest space on the disc will be reserved for the listing, which may leave no 
space for the code file. A good rule of thumb is to use twice the number of blocks used by 
program file. For example, if TOMS: PROG RAM. TEXT is 20 blocks long, a size specification of 
40 blocks is made for the listing file. 

T0MS:PR0GLIST.TEXT[40] 
(Be sure to include the period at the end of the file name. ) 

It is possible to have a CRT screen listing by specifying "CONSOLE:" as the listing file. This is 
not recommended unless the program is very small, or an "error only" listing was requested. 
The listing will be scrolled onto the screen and you are returned to the Main Command Level. 
There is no way to control the screen listing. 

Object File Specification 

Finally, you are prompted to give a name for the code file that will be generated by the 
Assembler. The default name is that of the source file with the suffix: ".CODE" replacing 
".TEXT". 

Output file (default is TOMS : PROGRAM . CODE ) ?_ 



If the default name is acceptable, press (Return) or (ENTER) . If you want to specify another name, 
enter the complete file specification. 

After this entry, the Assembler begins processing your program. The CRT displays when the 
first pass of the Assembler is completed along with the number of errors encountered during the 
pass. There is a similar display for the second pass. After the second pass is completed, you are 
returned to the Main Command Level. If no errors were generated during the assembler, a code 
file was created. 



If the assembly program is executable (has a start address), you may run it by pressing ( R ) at 
the Main Level. The Run command will run your program automatically until: 

• another program is assembled or compiled. 

• a workfile is specified. 

• the computer is powered down. 

• the system volume is re-specified. 

If the Run command no longer works for your program, use the eXecute command and give the 
name of the code file that was generated. 
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Interpreting the Listing 

The output from the Assembler contains the following information. The first column on the listing 
indicates the (decimal) number of the source-program line. For each line of source, a line number is 
generated. This is true of blank lines as well. 

The second column shows the location counter (relative to the code origin). The value is in hex 
notation unless the DECIMAL pseudo-op is specified. When the program is loaded, the number in 
column two can be added to the base address of the load to obtain the absolute address of the 
instruction. This is useful information when debugging. 

The third column shows the hexadecimal (base 16) representation of the machine code for the 
instruction or value of equated symbols generated by the Assembler. 

The right side of the listing is a copy of the source program. 

Sample Assembler Output 



Line Number 


Address 


Emitted 1 
Code 1 




Source Code 


3B 


00000000 




r o r S 





37 

38 00000000 0000 0000 s impl e2_ze ro del 0.0 

38 00000004 0000 0000 

39 

40 00000008 4E41 5 imp 1 e2_in i t i al i ze trap «1 (stack check) 

41 0000000A 0000 dc.u (no local space) 
42 

43 0000000C 4CFA 0300 movent. 1 s impl e2_ze ro 1 aO-a 1 

FFF0 

44 00000012 48ED 0300 movent. 1 aO-al ts um ( a5 ) 

FFF0 
45 

46 00000018 4E5E unlk aS 

47 0000001 A 4E75 rts 
48 

49 0000001C 4E41 s impl e2_pa rt add trap *1 

50 0000001E FFFC dew -4 
51 

52 0000 0010 result eiu IB 

53 0000 000C x eiu 12 

54 0000 000B y enu 8 (relative to aB) 

55 0000 0004 ret-addr eiu 4 



Error messages are listed under the line in which they occur. At the completion of the assembly, 
the number of errors will be displayed. If there are errors, there will be a directive for you to 
check the location of the last error in the program. At that location there will be a description of 
the error. Also listed will be the location of the error above it if one exists. In this manner, all 
errors can be located without having to search the whole listing. 
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The Programming System 

It is assumed that you will be writing most of your programs in Pascal. In the instance where the 
execution speed of a particular routine is insufficient, this section will show you how to translate the 
Pascal routine into an assembly language routine and call it from your Pascal program. 

It is possible to write a simple procedure, put it in the system library (usually a file named LIBRARY 
on the * volume), and access it with an EXTERNAL declaration from the Pascal program. Howev- 
er, add some interface text to the routine, and you have created a module. The benefits of modules 
are that global variables and constants may be used for communication among modules. Special 
types which define parameters need only be declared in the module containing the called proce- 
dure. 

A Pascal module was developed for use as an example. The Librarian was used to disassemble the 
code into its assembly language counterpart. The intent of this section is to explain the method of 
interpreting the disassembly information and producing a working Assembler language module. 
The listings of the examples are included at the end of this chapter. The examples are also available 
on the documentation disc (DOC:). The file (ASMB_P1) imports the file (ASMB_M1). These are 
both Pascal files. The Pascal file (ASMB_P2) imports the Assembler language file (ASMBJVI2). 

You'll notice in the example program that the variables are declared to be of the type which are 
defined in the imported module. If the program merely declared one or two of the procedures to be 
EXTERNAL procedures, those special types would have to be defined in every program that called 
the procedures. It would be like going to the Library for a book and having to write down the table 
of contents every time you wanted to use the book. 

For your Assembler language module to interface cleanly with the Pascal program, the conventions 
of the Compiler must be followed. That is, you must set up the Assembler language module to act 
as if it were a compiled Pascal module. You must also exit the module leaving everything in order, 
as a Pascal module would. 

The information you need to accomplish a clean "Pascal-to-Assembler language" interface is 
presented in this section. You should understand how the Compiler: 

• Prepares interface text (IMPORT text) 

• Declares entry points (DEF table) 

• Declares external references (EXT table) 

• Passes parameters 

• Creates global variable space 

• Initializes modules 

• Recovers from errors 

• Returns from subroutines 

You will find a listing of the Pascal program and module as originally written, a listing of the 
disassembly of the module, and a listing of the final, working Assembler language module. These 
listings are included at the end of this section. It might be helpful to remove them from the manual 
and keep them out for reference as you're reading this material. 
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The first subject covered is the method of generating the IMPORT text. This is what separates 
an importable module from a simple external routine. The subsequent material is of concern in 
either case. There will be a short explanation of the method for declaring EXTERNAL routines 
toward the end of the section. 

The IMPORT Text 

Certain information must be passed from an imported module to the Compiler to complete the 
module interface. This information is the IMPORT text. Actually, IMPORT text contains IM- 
PORT declarations and EXPORT declarations. It's called IMPORT text because it's what the 
Compiler needs when it is importing the module. It must know the module name, global 
variables, global constants, and procedure and function names. If special TYPE declarations are 
needed to define the variables, they must be included in this information. 

At compile time, your imported Assembler module must make this information available to the 
Compiler. This is done with the SRC pseudo-op. See how the IMPORT text of the Pascal listing is 
exactly the same as the SRC-IMPORT text below. 

src module simple2! 

src export 

src type 

src rec = record 

src ii : inteSeri 

5 re i 2 : int e 9e r i 

src end! 

src const 

src zero = rec[il:0»i2:0]i 

src war 

src lastre~su.lt : rec! 

src procedure in i t i.a.l i 2 e i 

src procedure a d d ( a i b : rec! 

src uarout:rec)i 

src end! 

The SRC section does not actually name the module or get the global space. There are separate 
techniques for accomplishing these things, which are discussed later. 

The DEF Table 

The DEF table contains the locations of all the entry points in the Pascal module and the 
location of its global space. This information is provided for the linking loader. The information 
is used to link all the modules together before they can be loaded and executed. 

DEF 



table 


of 'SIMPLE': 




SIMPLE 

SIMPLE. 

SIMPLE. 

SIMPLE. 

SIMPLE. 


.ADD 

.INITIALIZE 
.SIMPLE 
.ZERO 


Gbase 

Rbase+82 

Rbase+10 

Rbase+252 

Rbase 



The symbol "SIMPLE" which is the same as the module name, is the name of the module's 
global variable space. This symbol is entered into the DEF table automatically when you 
reserve the global space using the COM statement. This is explained later in the global variable 
section of this chapter. 
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"SIMPLE^kDD" AND "SIMPLE_INITIALIZE" are the entry points into the two procedures "add" 
and "initialize". When writing Assembler language routines, they must be named as the Compiler 
names its procedures. The Compiler appends the module name to the front of the procedure 
name, separated by an "_". When the Compiler looks at your IMPORT section, it assumes that the 
procedures have been named by its convention. When it's time for the loader to hook everything 
together, it looks for those procedure names in your module's DEF table. 

"SIMPLE-SIMPLE" is the entry point, or location, of the module initialization body. Module 
initialization is discussed later in this chapter. 

"SIMPLE_ZERO" is the location of the structured constant, "zero", which appears in the 
IMPORT section of the module. Any code which resides in the assembly module and is de- 
clared in the IMPORT section of the module, must appear in the DEF table. It, too, must be 
named by prefixing the module name to the constant name that you declare in the IMPORT 
section. This name must appear as a label at the constant's location in the program. 

You must create a DEF table for the Assembler version of your routine. This is done using the DEF 
statement. Notice that all the symbols in the Pascal module's DEF table are named in the DEF 
statements below except the symbol for the global variable space. The global variable symbol is 
entered into the table at the time the space is reserved with the COM statement. 

def simple2_add 

def simpl e2_in i t i al i ze 

def simple2_zero isimple2_simple2 

The EXT Table 

The EXT table that you get from the Librarian is the list of the symbols that the loader must find 
in some corresponding DEF table so our module can access those external items. 

EXT table of 'SIMPLE': 
SYSGLOBALS 

"SYSGLOBALS" is the only symbol in this particular list. We need to access some of the 
system's global variables in our routine so we must know where they are kept. They are in the 
global variable space for the system, "SYSGLOBALS". (See the TRY-RECOVER section for 
more details about the system globals. ) 

The EXT table is created in the Assembler module using REFA and REFR. Both instructions enter 
symbol names into the EXT table. REFA causes the symbol to be referenced using absolute 
addressing. REFR causes the symbol to be referenced using 16-bit PC relative addressing. See 
REFA, REFR, SMODE and LMODE in the pseudo-op reference section. 

In the example, "SYSGLOBALS" was declared as external using REFA. 

If other modules' global variable sections were to be referenced, the symbol for those areas 
would also need to be included in our EXT table. This is explained in the global variable 
section. 
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Declaring the Module Name 

The module is named using MNAME. This puts the name of the module in the module directory 
for the Compiler to reference when importing the module. 

If no MNAME is used, the module name will be the same as the file name. 

Passing Parameters 

When parameters are passed to a procedure, the values or addresses of variables in the 
parameter list are pushed onto the stack. The function result space is put on the stack if the 
routine is a function. The leftmost variable in the parameter list is pushed onto the stack. Then 
the rest are pushed onto the stack in order from left to right. The return address is pushed onto 
the stack automatically by the processor at the time the JSR instruction is encountered. 



For exampl 


e: 




114 


2F0E 




lie 


487A 


005A 


120 


2B4F 


FFF6 


124 


538F 




126 


2F2E 


FFFO 


130 


2F2E 


FFF8 


134 


4EB« 


FF98 


13B 


2B5F 


FFF8 


142 


588P 




144 


2F2E 


FFF4 


148 


2F2E 


FFFC 


152 


4EBA 


FF8B 


156 


2B5F 


FFFC 


ISO 


202D 


FFF8 


164 


D1AD 


FFFO 



mo u e . 1 aGi-(sp) 

pea Rbase+208 

move. 1 sp .SYSGLOBALS-KK a5 ) 

subfl . 1 *4 isp 

move .1 -16( a6) »- ( sp) 

move .1 -8< a6) t- ( sp ) 

isr Rbase+32 

moue.l ( sp > + iGbas e-8 ( a5 ) 

iub«ul »4,sp 

moue .l-12(a6)i-(sp> 

move .1 -4(aS) i- ( sp) 

Jsr R base +32 

moi.ie.l (sp)+>Gbase-4(a5) 

move . 1 Gbase-8(a5) >d0 

add.l d0iGbase-16(a5) 



The stack is mapped in the following way: 



12(SP)- 
8(SP)- 



4(SP) — 
(SP)— 



FUNCTION RESULT 



VALUE of x 



VALUE Of y 



RETURN ADDRESS 



Notice that the stack grows downward (toward smaller addresses). 



If a parameter is passed by reference, a 4-byte address is pushed onto the stack. When passing 
by value, values up to 4-bytes are pushed onto the stack, but larger values are essentially 
passed by reference. That is, a 4-byte address is pushed on the stack. In this case, a copy of the 
value must be made in local variable space so that the actual parameter is not altered. This is 
illustrated in the Local Variable section. 

More information can be found in the Compiler chapter under the heading "How Pascal Uses 
the Stack". 
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Declaring Global Variables 

You must understand how the Compiler allocates global variable space so that you get and use 
global space the same way. The value stored in register A5 is the base address for all global areas. 
Each module that declares global variables is allocated an area for them. The symbol assigned to 
the area is the distance from the base address in A5 to the top of the global area. Globals are then 
referenced symbolically, using the global area name and offset relative to A5. 

The name for the location of a module's globals (relative to the address in A5) is the same as the 
module name. So the symbol for the global area for "module simple" would be "SIMPLE". 

Determine how much space you need for your globals. When determining how much space is 
needed, you must also consider any variables that are internally global to the module. Notice on the 
Pascal module listing that the variable "sum" is global to the module. 

If you are rewriting a Pascal module as we have done in the example, the Compiler provides 
variable size information beside the variable declarations on the listing (the negative number). More 
detailed information can be displayed using the Compiler's $TABLES$ directive. In Assembler 
language modules, you must also specify the size as a negative value. Declare global space using 
the COM statement: 

COM sifTtPleZ »-lB 

The value, - 16, corresponds to the total size of global variables "lastresult" and "sum". Both 
are records containing two integers each. 

The COM statement also enters the symbol into the DEF table. 

Referencing Global Variables 

The Assembler module name is SIMPLE2, as is its global base. Notice in the DEF Table that 
"SIMPLE" is equal to "Gbase" (Global BASE) for the Pascal module. Global locations in the 
disassembly of the Pascal module are referenced using the symbol "Gbase" rather than "simple". 



DEF table of 'SIMPLE': 






SIMPLE 




Gbase 


SIMPLE-ADD 




Rbase+82 


SIMPLE-INITIALIZE 




Rbase+10 


SIMPLE-SIMPLE 




Rbase+252 


SIMPLE-ZERO 




Rbase 


170 202D FFFC 


move . ! 


I 6b:;as«-4(a5) idO 


174 D1AD FFF4 


add. 1 


do ,Gbase-l2<a5) 


178 4E7G 


t rapv 




180 206E 000B 


■ ovea 


. 1 8<aG) taO 


1B4 4CAD 1E00 


diuu em 


• u Gbase-8 ( a5) tal -a4 
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When writing your Assembler language module, use the COM symbol to reference globals. The 
Assembler doesn't recognize "Gbase". In our Assembler module, the global variables are refer- 
enced using "SIMPLE2". 

lastresult enu simple2-8 

lastresult_il eiu simple2-8 

lastresult_i2 e q u simple2-4 

sum enu simple2-lB (all are relative to a5) 

5um_il Bqu simpleZ-16 

5um_i2 bru siwple2-12 

escapecode eiu svs3lobals-2 

reoouer_reo e q u svsSlobals-10 



Note 

When structured variables are used, the individual elements of the 
structure are referenced at progressively higher addresses within the 
structure's space. 

If, for example, you had declared two integers separately instead of together in one record, you 
would refer to them as: 

1 ast resul t_i 1 EOU si<riple2-4 

last result_i2 EOU simple2-8 

Referencing Other Module's Globals 

When referencing the global variables of another module, it is necessary to establish the 
external reference using REFR or REFA. 

The individual variables are referenced at negative offsets from the symbol and relative to A5, 
as described in the global variable section above. As was mentioned previously, offsets into 
data areas are provided on Compiler listings. 

Local Variables 

There are several methods for getting local variable space. The following method is recom- 
mended for those intending to produce purely relocatable code. This is important if the code is 
to be committed to ROM. 

Notice that the first instruction in each of the disassembled routines is: 

TRAP «1 

TRAP #1 calls a system routine which allocates local variable space in a new stack frame. A 
check is made of available stack space. If there isn't room on the stack, a "Not Enough 
Memory" error is reported and control is transferred to the Main Command Level. 

The TRAP #1 routine then executes a LINK instruction. The LINK instruction is explained in detail 
in the MC68000 and MC68020 manuals, and in the Compiler chapter under "How Pascal Uses 
the Stack". 
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Our Assembler does not understand the double operand format of the TRAP instruction as it is 
printed in the disassembly listing. The size of the stack frame is specified following the TRAP 
instruction in a DC.W instruction. The value of the constant in the DC.W instruction specifies 
the amount of space needed for local variables. 

The following illustration shows the stack before the function "part_add" gets its local variable 
space. 

Before the LINK: 



After the LINK: 



12(SP) 

8(SP) 

4(SP) 

(SP) 





FUNCTION RESULT 




VALUE Of x 




VALUE of y 




RETURN ADDRESS 



16(A6)- 

12(A6)- 

8(A6)- 

4(A6)- 

(A6)- 

-4(A6)- 



FUNCTION RESULT 



VALUE Of x 



VALUE of y 



RETURN ADDRESS 



OLD (A6) 



Temp 



"(SP) 



Parameters are now referenced relative to A6 instead of SP. Local variables are referenced at 
negative offsets from A6. 
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Local variable space is also needed for copies of some value parameters. As was discussed in 
the parameter section, value parameters which are larger than 4 bytes have their address put on 
the stack in place of the value. In order not to alter the value of the actual parameter, a copy 
must be made in local variable space. Allocate the space using the TRAP instruction, then 
immediately move the values of the value parameters into the local variable space. This is the 
case with the parameters to "Procedure Add". 



16(A6) 

12(A6) 

8(A6) 

4(A6) 

(A6) 

-4(A6) 

-8(A6) 

-12(A6) 

-16(A6) 





ADDRESS of a 






ADDRESS of b 






ADDRESS Of OUT 






RETURN ADDRESS 






OLD (A6) 






COPY of b.i2 






COPY of b.il 






COPY of a.i2 






COPY of a.M 





(SP) 



This mapping was accomplished by the following block of code: 



7G 


504F 




ad<H . w »8 »sp 






7B 


4ED0 




Jmp ( aO ) 






80 


0000 




dc.wO ordc.b 


i0 r d 
c t m pi p onn 


c.b 


82 


4E41 


FFF0 


trap «*i t*- IS 






8E 


Zt'SE 


0010 


»ni'«.! LB: aF. J r«fc 






SO 


2D5B 


FFF0 


moue.l (a0>+ t-18(*6) 






aa 


2D50 


FFF4 


siave, 1 : a0: t-iH&fi 






;•" SB 


. . ■■£ 


000 = 


mouea. 1 12( aB) »a0 






102 


2D5B 


FFF3 


*»-'«,! ;a0)*,-a(aS) 






iob 


::■ . 


FFFC 


mo« % s i i at= > ,-$i 28 's 






110 


2F2D 


FFFB 


moue.l SYSGL0BALS-10( 


a5) .-( sp) 




114 


2F0E 




moue.l aB t- ( sp ) 






116 


487A 


005A 


pea Rbase+208 






120 


2B4F 


FFF6 


moue.l sp .SYSGL0BALS- 


10(a5) 
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Module Initialization 

Finally, it is necessary to include a module initialization body within each module. The initializa- 
tion body is a routine which is named by appending the module name to itself, separated by 

The purpose of module initialization is to allow for file initialization within the module. Even if a 
module declares no files, the Compiler emits a call to the module initialization body for every 
module imported into a program. It can be a null routine such as an RTS with the label tacked on to 
the end of the assembly: 

simple2_simple2 rts 

The name of the module initialization body must be marked as an entry point along with the 
other procedure names using DEF. 

Error Recovery 

The TRY-RECOVER escape mechanism can be written into assembly language routines for grace- 
ful termination of programs that generate errors. TRY-RECOVER is explained in detail in the "Error 
Trapping and Simulation" chapter. 

The section of code that could cause the error is enclosed within the TRY section. The TRY 
section creates a RECOVER-record on the stack. The record contains the location of the 
previous RECOVER-record, the stack frame pointer, (A6), and the location of the RECOVER 
code. The location of this record is saved in a special location that the system knows about. This 
location is at an offset of - 10 in "SYSGLOBALS" (operating SYStem GLOBALS). "SYSG- 
LOBALS" is relative to A5. 

An example of the TRY action is taken from the disassembly: 

mouea. 1 1G( aG ) »a0 

moue.l < a0)+ »-16< aG) 

inoue. 1 ( aO) »-12(a6) 

movea. 1 12( aG) taO 

moue.l (a0)+»-8(a6) 

moue.l ( aO) »-4< aG) 

niii'-e. 1 SYSGLG3ALS- iO' «5> .- .' s f- ) 

w.»e < I aB : '■ sf ! 

moue. 1 bp t3YSGLD3ALS-10(a5) 

subs .1 *4 >5P 

move .1 -lG(aG) t- (sp> 

moue .1 -B(aG) i- ( sp) 

Jsr Rbase+32 

moue.l ( sp) + iGbase-8( a5 ) 

After the above code has been written, write the code body of the routine. 



BG 


206E 


0010 


90 


2D58 


FFF0 


34 


2D50 


FFF4 


98 


20GE 


oooc 


102 


2D58 


FFF8 


106 


2D50 


FFFC 


110 


2f 2D 


FFFG 


-.1/1 


ZFOE 




: i IB 


-.= 7( 


005A 


" '■' " 


2B4F 


.:-..- 


1l1 


CDBP 




12G 


2F2E 


FFF0 


130 


2F2E 


FFF8 


134 


4EBA 


FF98 


138 


2B5F 


FFF8 



178 


4E7G 




180 


20GE 


0008 


184 


4CAD 
FFFS 


1E00 


180 


4830 


IE 00 


194 


ZBBF 
FFFB 


0008 


200 


DEFC 


OOOC 


204 


4EFA 


0024 


208 


2C5F 




210 


2B5F 


FFF6 


214 


70B4 




21B 


BOGD 


FFFE 


220 


6600 


0012 


224 


4CBA 


OFOO 
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The last piece of code must restore the pointer to the previous RECOVER-record and remove 
the current one from the stack. Control is then transferred to the instruction following the 
RECOVER section. For example: 

t r a p <.i 

movea . 1 8 ( aG ) »a0 

mouemiW Gbase-8 ( a5 ) i al - a4 

Mouem< w al -a4 i ( aO) 

Move.l 8«sp> »SYSGL0BALS-10(a5) 

adda*w «12»sp 

J»p Rbase+242 

mo v e a . 1 ( sp ) + » aG 

move.l (sp)+ .SYSGL0BALS-10(a5) 

moveq #100 »d0 

cmp.u SYSGL0BALS-2(a5) »d0 

brie Rbase+240 

movem.w Rbaseta0-a3 

If an error or exception does occur, the system stores the number of the error in a location at 
"Sysglobals-2(A5)" and looks at "Sysglobals-10(A5)" to find the location of the RECOVER- 
record. This location is loaded into the Stack Pointer register (SP). The location of the RECOV- 
ER routine is then popped off the stack and control is transferred to the RECOVER routine. The 
next value popped off the stack is the stack frame pointer for the RECOVER routine. It is moved 
to A6. Then the higher level RECOVER-record pointer is popped off the stack and moved to 
"Sysglobals-10(A5)". 

Once these values have been restored, you may examine the value at "Sysglobals-2(A5)" and 
determine what action to take. If you want to handle the error, you may do so. If not, execute a 
"TRAP #10" and the problem will ripple out to be handled by the higher level RECOVER 
routine. 

Here is the assembly version of the RECOVER routine: 

Jiitp Rbase + 242 

m a v e a . I ( s p: i + > a G 

move.l (sp>+»8YSGL0BALS-10(a5) 

M0M64 #100 fdO •• 

omp.w 5Y5GL0BALS-2<a5> »d0 
bne 'Beast +240 
"Mauentiw Rb.ase >aQ~a3 ". ' ^ . 

»ov(*iW i''i'Z"3 >Ghase -Si »5 ) 

bra Rbase+242 

trap » 1 

unlK aG 

m o v e a . 1 ( s p ) + > a 

adda.w »12 »sp 



204 


4EFA 


0024 


20B 


2C5F 




210 


2B5F 


FFFB 


214 


7064 




216 


B06D 


FFFE 


220 


GG00 


0012 


224 


4CB6 
FF1C 


OFOO 


230 


48AD 
FFFB 


OFOO 


23B 


G000 


0004 


240 


4E4A 




242 


4E5E 




244 


205F 




246 


DEFC 


OOOC 
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Exception Coding 

In your TRY block you may wish to raise certain exception conditions and handle them in the 
RECOVER section. This corresponds to the Pascal standard procedure ESCAPE. When the condi- 
tion is determined, store a 16-bit integer value representing the error in "SYSGLOBALS -2(A5)" 
and execute a TRAP #10. For example: 



32 


4E41 


FFFC 


t rap *1 t*-4 


3B 


202E 


oooc 


moue .1 lZt aG) »d0 


40 


DOAE 


0008 


add. 1 8(aG) »d0 


44 


4E76 




t rapu 


46 


2D40 


FFFC 


inoue.l dO»-4(«B) 


50 


4AAE 


FFFC 


' tst . I -4!a6) '.■'..'' 


54 


BC00 


000A 


b*s Bbase+SS 


58 


3B7C 

FFFE 


O0G4 


mme.w *100 .SYSGLD3ALS-Z(a5) 


S3 


4E4A 




t rap »10 


EG 


2DGE 
0010 


FFFC 


move. 1 -4(aG) .16<aG) 


72 


4E5E 




unlk aG 


74 


205F 




moue a. 1 ( sp ) + o0 


7G 


504F 




addq . u »Bisp 



The example generates an escape with escapecode 100 if lines 58-64 get executed. In your 
recovery section, check "SYSGLOBALS -2(A5)" to see if you recognize the value. If you do, 
make the appropriate recovery. Otherwise, your RECOVER section restores the old RECOVER- 
record location and issues another TRAP #10. Thus the error is passed on to the next RECOVER 
block. 

Returning to Pascal 

When returning to Pascal from assembly, the stack must be cleaned up, a function value must 
be left on the top of the stack if appropriate, and all Pascal dedicated registers must be restored 
(A5, A6 and A7). 

You can return to Pascal by leaving the return address on the top of the stack and executing an 
RTS, or you can store the return address in an address register and execute a JMP indirect 
through the address register. 



21G 


B0GD 


FFFE 


citip.w SYSGL0BALG-ZU5) »d0 


220 


GG00 


0012 


bne Rbase+240 


224 


4CBA 
FFIC 


0F00 


mouem.w Rbaseta0-a3 


230 


48AD 
FFF8 


0F00 


mouem.w aO- a3 »Gbas e-8 ( a5 ) 


236 


6000 


0004 


bra Rbase+242 


240 


4E4A 




trap #10 


242 


4E5E 




unlk sB 


244 


20 5F 




m o " e a . 1 ( s p ) + > a 


24G 


DEFC 


oooc 


a d d a . w * 1 2 > s p 


250 


4ED0 




' .. jmp C «t;)S : 


252 


4E75 




dc . u 20085 or dc . b 78 »1 17 



or dc . b 
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Declaring External Procedures 

Most of the subjects that have been covered in this section are relevant to EXTERNAL proce- 
dures. 

If you just want to write a routine, put it in the current System Library file (default is the "LIBRARY" 
file), and call it from Pascal by declaring it as EXTERNAL, you won't need to be concerned with 
IMPORT text. 

You will need to generate EXT and DEF tables. And you will have to deal with parameters. You 
may or may not want to deal with local variable space. If you want local space, you will 
reference your parameters relative to (A6). Otherwise, reference them relative to (SP). You will 
not have to write a module initialization body. 

The TRY-RECOVER mechanism is also optional. There's always a RECOVER routine some- 
where that has to handle those errors. The Operating System puts one around your program 
before execution. 

You must be concerned with the stack. All the parameters must be removed. It must be left in 
the condition it was in before the calling procedure started preparing for the call. 

You must be concerned with restoring A5 and A6 to their original values. 

Write the routine, assemble it, and use the Librarian to put it in the System Library. From Pascal, 
declare it as EXTERNAL, and call it just as if it were a Pascal procedure. 

Just remember — if you're not using standard types, every program that calls this routine will 
have to define the special types just as you had originally defined them. 
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Instruction Syntax 

This section provides details of the syntax of assembly language instructions required by the 
Workstation Assembler. 



Note 

Beginning with system version 3.1, the Workstation Assembler supports 
all of the 68020 processor and 68881 co-processor instructions. Thus, 
you can assemble programs that contain instructions which may not be 
executable by your computer. Consult the target computer's hardware 
documentation to determine which processor is installed in it. 

General Syntax 

Here is the syntax required for Workstation Assembler instructions. Each portion of the diagram is 
further described or expanded in the following paragraphs. 

Program Line Syntax 



»• line label 



— I - "V J — *" opcade — I 1 — I ',' 

I ^"*\ ) — *" operand (s) ' ^~*\ ) — *" comment — »■ 



^-+"(#) — »■ comment line 



Empty circles denote required spaces. Line labels and comment lines must begin in column 1. 

Examples 

Labels Opcodes Operands Comments 

RTS 
Label_9 STOP 

JSR Subr_name 
Sum ADD Dl »D2 This is a comment. 
* This whole line is a comment. 
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Instruction Fields 

There are no fixed-width fields within instructions; instead, space characters delimit the fields of 
instructions. For instance, the first space after a line label separates it from the subsequent opcode; 
the first space after the opcode separates it from the operand; and so forth. Therefore, the following 
two program lines are equivalent: 

Label ADD Dl »D2 This is a comment. 

Label ADD Dl »D2 This is a comment. 

This rule dictates that spaces are not permitted within the label, opcode, or operand fields, because 
the first space encountered after the start of the field ends that field. Instructions are otherwise 
free-format with respect to spaces; for example, comment fields may have any number of spaces, 
within the limits of the line width. 

Letter Case 

Upper- and lower-case characters may be used interchangeably, except inside of literal (quoted) 
strings. 

add dl » d2 

MOVE D2,(A1) 
BTst «31iD2 

dc 'This is a literal.' These two literals are not equivalent. 

dc 'THIS IB A LITERAL, ' 



Line Labels 



line label — ■<? 



-*/^\-»op 



v_*/ \-fc- uuera id ;-! ' ^"*\ J — •" 



comment 



^"■*/ #Y— ■ *■ comrnen 



it linn 



If a line label is present, it must start in column 1 of the line. The opcode must start in column 2 or 
later (or it will erroneously be considered to be a label). 

12345678901 2345S78901234567890 1234567890 

Label MOVE Al »A2 Comment field. 
MOVE Al »A2 Comment field. 



Line labels are in a class of objects called symbols, which are described in the "Symbols" discussion 
of the subsequent "Operands" section. 
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Opcodes 



l iti« 1 s&el f— -^ 



*^( J — ^ opco 



v_W^ }— •"" otJei-ard (si ^ *"•*% J — "^ cummeiit j — m 



*-*■£# J— *» cofriment line 



Opcodes (operation codes) are mnemonic abbreviations used for specifying machine language 
instructions. Here are some examples: 

ADD 
JSR 
MOVE 

The term "opcodes" includes these three types of codes: 

• Processor opcodes 

• Co-processor opcodes 

• Assembler pseudo-opcodes (or simply "pseudo-ops") 

Processor and co-processor opcodes are described in this section. Assembler pseudo-ops are 
described near the end of the chapter. 

Processor Opcodes 

All opcodes described in the 68000 or 68020 user's manuals are supported by the Workstation 
Assembler. Since the syntax and semantics of each instruction are fully described in those manuals, 
they will not be described here. 

Note that some instructions have Address, BCD, Immediate, or Quick forms. When possible, 
Motorola's assembler automatically generates machine instructions for these opcodes (for optimiza- 
tion). However, the Workstation Assembler does not, unless explicitly told to do so. 

Co-processor Opcodes 

Co-processor opcodes are supported by the Workstation Assembler. See the MC68020 user's 
manual for a general description of the syntax and semantics of each Details of particular co- 
processors, such as the 68881, are provided in the documentation for the corresponding product. 
See the "MC68881 Support" section for a description of exceptions to the syntax and support 
suggested in the MC6888 1 document. 
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Size Suffixes 

Size suffixes can be appended to both of the following items: 

• Opcodes 

• Index registers (in operands) 

They specify the size of operand(s) used by the instruction. 
The available size suffixes and their definitions are as follows: 



Suffix 


Meaning 

Byte 


Data Size 


Where Used 


B 


8 bits 


Opcodes only 


S 


Short 


8 bits 


Opcodes (Branch instructions only) 




Single 


32 bits 


MC68881 opcodes only 


w 


Word 


16 bits 


Opcodes and index registers 


L 


Long 


32 bits 


Opcodes and index registers 


D 


Double 


64 bits 


MC6888 1 opcodes only 


X 


Extended 


96 bits 


MC68881 opcodes only 


P 


Packed BCD 


96 bits 


MC6888 1 opcodes only 



All instructions that can operate on more than one data size will assume the default size of word (16 
bits) unless a size suffix is explicitly specified. 

Here are some examples of using these suffixes: 

ADD registers as Bytes 

ADD registers as Words 

ADD registers as Words (default operand length) 

ADD registers as Long words 

16 bits of A2 are used as index (default) 
32 bits of D2 are used as index 

Branch on EQual; destination specified by 8 bits 
Branch on EQual; destination specified by 16 bits (always) 
Branch on EQual; destination specified by 8 or 16 bits 
Branch on EQual; destination specified by 32 bits 



ADD, 


,B 


Dl 


»D2 


ADD, 


,W 


Dl 


»D2 


ADD 




Dl 


»D2 


ADD, 


,1 


Dl 


»D2 



ADD (A1.A2.W)»D1 
ADD (A1»DZ.L)»D1 

BEQ.S Label. 

BEO.W Label. 

BEO Label. 

BEO.L Label. 



FSGLDIV.S FP0»FP1 Single-precision division: FP0/FP1 
FSGLMUL.S (AO).FPl Single-precision multiply: (A0)*FP1 
fmove.d *3.14,FP0 Double-precision move: 3.14 to FPO 

Note that in the BEO instruction with no suffix, the Assembler determines whether it will use 8 or 16 
bits to specify the destination. In contrast to this, the BEO . w opcode specifies that 16 bits will be used, 
even though the destination might fit in 8 bits. 
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Operands 



-.'.-it: -;«-.- r„ — --' 



•( J— -» ooco 



Lq- ^^7^t> ^ Lq» 



"<*Mi 



IBiiMlBliilfiBli 



Operands specify the data upon which the operation is to be performed. They are composed of any 
of the following: 

• Constants 

• Symbols 

• Expressions containing constants, symbols, and operators 

• An instance of an addressing mode (see the subsequent "Addressing Modes" section for 
further information) 

Constants 

Constants are sequences of ASCII characters that define a numeric value. There are basically four 
types of constants: 

• Decimal numeric constants. 

123 
2147000111 

Note that decimal numeric constants may contain any decimal digits o through 9; however, 
they may not contain a sign character (+ or -), which would make them an expression (see the 
subsequent "Expressions" section). 

• Hexadecimal numeric constants. 

$19 
$FF20 

A * preceding a numeric constant indicates that it is a hexadecimal (base 16) quantity. 

• Floating-point numeric constants. 

3.14 
5.01E9 
-3.14E-99 
2.718E-231 

The syntax requirements for these constants are the same as for Pascal floating-point (real) 
constants. See the "Real and Longreal Literals" section of the "Numbers" entry in the HP 
Pascal Language Reference for details. 



242 The Assembler 



• Literal character constants. 



■>zi' 



When the characters are enclosed within single quotes, the Assembler emits a series of bytes, 
one per character, each of which contains the ASCII code of the corresponding character. 

Literal character constants may contain to 4 characters. If the single quote character ( ' ) is to 
be part of the constant, you must put two quotes in the literal. 



/ - / / L / 



Literal isa'b 



Symbols 

Symbols are names used in place of values or registers. Symbols must begin with an alphabetic 
character, but they may subsequently contain digits (0..9), s, * and _ as well as alphabetic charac- 
ters. Here are some examples: 

Symbol 
SYM.2 

MAIN main 

Z@_$13 

Symbols may contain any number of characters. The only restriction is that each instruction must 
be contained entirely on one line. Note also that upper-case and lower-case letters are considered 
equivalent in symbols; i.e., the symbol main is equivalent to the symbol main. 

Here are examples of using symbols in instructions: 

Symboll EOU RBase+32 
JSR Symbol 1 

ADD (SymbolZtAl) »D1 

The Location Counter Symbol 

The * character is a symbol that signifies the value of the Assembler's location counter (except 
when the * is in column 1, which indicates a comment line). Here is an example of using the symbol 
in a branch instruction. 

BRA *-2 

The location counter points to the memory address at which the instruction begins, and thus is 
analogous to the processor's program counter (PC). In fact, * is equal to the program counter at the 
point the instruction is fetched; however, the PC varies from * by 2 or 4 bytes at the point the 
operands are fetched. 
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Symbol Types 

Here are descriptions of the various types of symbols known to the Assembler: 

• Pre-defined register symbols are any of the following: 



Symbol 



Register Specified 



AO thru A 7 Address registers thru 7 

CCR Condition Code Register 

CACR CAche Control Register 

caar CAche Address Register 

DO thru D7 Data registers thru 7 

dfc Destination Function Code register 

fpo thru FP7 Floating-Point co-processor registers thru 7 

fpcontrdl Floating-Point co-processor control register 

fpstatus Floating-Point co-processor status register 

F P I A D D R Floating-Point co-processor Immediate ADDRess register 

I s P Interrupt Stack Pointer ( A7 ' ) 

MSP Master Stack Pointer (A7") 

SFC Source Function Code register 

SP Stack Pointer (same as USP and A7) 

SR Status Register 

USP User Stack Pointer (same as SP and A7) 

VBR Vector Base Register 

Note that the symbolsFPCONTROL, FPSTATUS, and FPIADDR are deviations from Motorola's 
assembler symbol names; however, you can define the Motorola register symbols as shown in 
the third example below. 

• User-defined register symbols are created with the EOU (equate) pseudo-op: 

StackPointer EOU SP 

M/AddressRei EOU Al 

STATUS EOU FPSTATUS 

Note that these are the only type of symbols that need to be defined before they are used. 

• Absolute symbols are those which either follow an ORG pseudo-op or are equated to an 
absolute expression. Here are some examples: 

ORG *FFFFF000 

AbsSvutl EOU *FFFFFED2 

AbsS'/iTi2 EOU AbsS/ml + lB 

AbsSvni3 EOU RelSviiil-RelSym2 Note: DIFFERENCE of 2 relatives is absolute 
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• Relative symbols are those which follow a RORG pseudo-op or are equated to a relative 
expression. 

RORG * Relative to ProSram Counter (PC) 

RelBvwl EQU RBase+lG 
RelSymZ EQU RelSymi 

RelSym3 EOU RelSym2+AbsSyi.i2 Note: CANNOT add 2 relatives 

• External symbols are those which are defined in another module (by a def Assembler 
pseudo-op, or by another language's compiler). They can be either absolute or relative. Here 
examples of how external symbols are defined (in the module to which they are external): 

REFA AbsExtSyml Absolute external symbol. 

REFR RelExtSyml Relative external symbol. 

Expressions 

Expressions are the general case of operand: they may be just symbols; or they can be more 
complex combinations of symbols, constants, and operators. The operators in expressions are 
limited to the following: 

• - subtraction, or unary minus 

• + addition, or unary plus 

• ! bit-wise logical OR 

• & bit-wise logical AND 



-0- 



~0- 



symbol 



CL 



Expressions are evaluated in strict left-to-right order, and parentheses are not allowed. Only one 
external symbol, or symbol equated to an expression containing an external symbol, is allowed per 
expression. Also note that you cannot add two relative symbols (although you can subtract two, 
since the difference is an absolute value). 



2+2 

RelSyntl+48+$DF00 

Rel5yitil-RelSym2+RelSym3+AbsExtSyinl 

AbsSyfnl-AbsSym2+RelSym3+AbsSyfii3 
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Addressing Modes 

The Workstation Assembler supports all of the addressing modes of the current 68000 family of 
processors; this section describes the syntax required to access each mode. 

With system version 3. 1, the Workstation Assembler was updated to support the 68020 processor's 
addressing modes. Since these new modes cannot be accessed with the old address syntax, new 
syntax is required. However, note that the old 68000 syntax is still supported in all instances. 

The following table shows the syntax and operand components of all supported addressing modes. 
Descriptions of operand components are given in the legend on the next page. 



Description of Mode 



Data Register Direct 

Address Register Direct 

Address Register Indirect 

Address Register Indirect 
with Post-increment 

Address Register Indirect 
with Pre-decrement 



Old Assembler 


New Assembler 


Dn 


same 


An 


same 


(An) 


same 



(An) + 



(An) 



same 



same 



Address Register Indirect 
(absolute displacement) 


dl6(An) 


(bd»An) 


Address Register Indirect with Index 
(absolute displacement) 


d8(An,Rn.SIZE) 


( bd > An ,Xn . SIZE*SCALE ) 


Memory Indirect Post-indexed 


n/a 


(cbd.Anl ,Xn.SIZE*SCALE,od) 


Memory Indirect Pre-indexed 


n/a 


([bd»An»Xn.SIZE*SCALE] ,od) 


PC Memory Indirect Post-indexed 


n/a 


( crbdi ,Xn.SIZE*SCALE ,od> 


PC Memory Indirect Pre-indexed 


n/a 


(Crbd.Xn.SIZE#SCALE] ,od) 


Absolute Address 


Expr 


same 


Program Counter Indirect 
(relative displacement) 


rdl6 


rbd 


Program Counter Indirect with Index 
(relative displacement) 


rd8(Xn.SIZE) 


(rbd,Xn.SIZE*SCALE) 


Immediate Data 


*Expr 


same 


Register List (such as for MOVEM) 


Ai-Aj/Dm-Dn 


same 


Bit Field Specifier 


n/a 


operand* offset : width > 
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Legend: 



An = Address register symbol: AO thru A7 

Dn = Data register symbol: DO thru D7 

Xn = Index register symbol: AO thru A7, or DO thru D7 

Rn = Equivalent to Xn (see above) 

d8 = absolute expression (8-bit): -2 7 thru2 7 -l 

dl6 = absolute expression (16-bit): - 2 15 thru 2 15 - 1 

bd = absolute expression (32-bit): - 2 31 thru 2 31 - 1 

od = absolute expression (32-bit): - 2 31 thru 2 31 - 1 

rd8 = relative expression (8-bit) : PC - 2 7 thru PC + 2 7 - 1 

rdl6 = relative expression (16-bit): PC - 2 15 thru PC + 2 15 - 1 
rbd = relative expression (32-bit): PC - 2 31 thru PC + 2 31 - 1 

SIZE = literal: W (or no suffix) specifies Word operand 

L specifies Long word operand 

SCALE = literal: 1 

2 

4 
8 

n/a = not implemented in the older "68000" Workstation Assembler 

Expr = expression (relative or absolute) 

Ai-Aj/Dm-Dn = List of registers: - means "thru"; / means "and". 

The values of i, j, m, and n can range from thru 7. 

Examples: A0-A3/D1-D4/A5, and D5-D7/D0/A0 

operand = any of the operands allowed with instructions that can operate on "bit fields". 

offset = literal or symbol that specifies starting bit of a bit field, 
width = literal or symbol that specifies number of bits in a bit field. 
Examples: D7{2:3>, and (A0KD1:D2> 

Operand Components: Order and Optionality 

In the above table, an operand is the whole quantity shown in one column entry. Here are some 
examples of single operands: 

AbsExprKAl >A2.L) 
(AbsExpr2»Al tD3.W#4) 
(CAbsExpr3.A4] »A3.L .AbsExpr-3) 

Thus, some of the components of these operands are AbsExpri, Al, A2.L, AbsExprZ, D3.W#4, and so 
forth. 
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The newer Workstation Assembler allows you to vary the order of these operand components 
(however, only with the new 68020 syntax). Here are some examples of varying the order of 
operand components (note that all these operands are equivalent): 

([AbsExpr3»A4] tA3.L .AbsExpr4) 
<[A4»AbsExpr3] »A3.L ,AbsExpr4) 
([A4.AbsExpr3] ,AbsExpr4 t A3.L) 
(AbsExpr4.A3.L»[A4»AbsExpr3]) 

The Workstation Assembler also allows you to optionally omit some of the operand components, as 
shown in the following examples (these operands are nor equivalent): 

([AbsExprl (All ,A5,L ,AbsExpr2) 

([All ,A5.L»AbsExpr2) 

([AbsExprl] ,A5.L) 

(CAH) 

(Dl) 

Note that whenever any operand component is omitted, an effective value of is used for that 
component. 

Comments and Comment Lines 



- lo- ■ = . . - -' 



o- 



_ . . 



^-*{\-*" . ijBi-snd :s) ' ^*Q- »» 



**-*/#) — *■ comment 



it line 



The first space following an operand (or the opcode in an instruction with no operands) terminates 
it; the remainder of the characters on the line, if any, are regarded as comments. 

Label ADD Dl iD2 This is a comment. 

RTS This is also a comment (since RTS has no operands). 

An asterisk (*) in column 1 indicates that the entire line is a comment; therefore, any instructions on 
the line will be ignored. 

12345G7B90123456789012345G78901 234567890 

* These are comment lines. 

* Add word addressed by Al to the ualue of the error counter. 

# 
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Notes 
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MC68881 Floating Point 
Co-processor Support 

This section describes the Motorola MC68881 floating point co-processor support provided by the 
HP Pascal Workstation Assembler. Note that the support provided by the Assembler is a subset of 
the co-processor's full capabilities. 

Assembler Support of the Co-processor 

The co-processor support provided by the Assembler is given in the list below. This list also includes 
those capabilities not supported. 

• All opcodes are supported. 

• All sizes and types of operands are supported, with the exception that floating-point constants 
and immediate operands are restricted as follows: 

• The floating-point literal constant syntax is that defined in the HP Pascal Language 
Reference under "Numbers", such that a period must be present, and the "L" expo- 
nent flag is not allowed (i.e. only the "E" exponent is allowed). 

• Only double-precision constants are allowed (i.e. ",D" size suffix). 

• The size suffix ".D" must explicitly be given. 

• All non-zero constants and immediate operands are normalized (i.e. 0.0 and normal- 
ized are the only supported IEEE types). 

• Use of floating-point values in expressions is not supported. 

• Single-precision division (FSGLDIV) and single-precision multiplication (FSGLMUL) may use 
any sizes except ".X" and ".D". 

• Assembler Pseudo-op DS allocates space in memory for all types and sizes of operands. 

• Assembler Pseudo-op DC, which reserves storage space, only supports double-precision oper- 
ands (i.e. ".D"). 

• No pseudo-ops (directives) are provided to control the rounding mode, so the default of 
"round to nearest integer value" occurs. 

• No pseudo-ops (directives) are provided to allow use of different co-processors. Therefore, the 
default co-processor id of 1 is used, which is the MC6888 1 co-processor. 

• The structured "IF" recommended in the MC68881 specification is not supported. 
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Assembler Pseudo-Op Reference 

The following is a list of the commands which direct the assembler to take the described actions. For 
a list of the Assembler-language and machine-language instructions, see the MC68000 User's 
Manual. 



COM 



Used to define a global area. 



( COM J — »- symbol -"*"\ ' )— *" size — H 



Item 


Description 


Range Restrictions 


symbol 
size 


An identifier for the global area 
A numeric expression 


see "Symbols" 
-2 31 thru2 31 -l 



Semantics 

The exact location of the global area will be determined at link time. The symbol is DEFined as an 
entry point. The amount of space is specified by the absolute value of the expression. If size is 
negative, the value of the symbol will be the offset from (A5) to the top of the global area and 
variables will have negative offsets from the symbol. This is how the Compiler does it. If size is 
positive, the symbol's value will be the bottom of the area, relative to (A5), and offsets will be 
positive. Only one COM statement allowed per assembly. 
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DC 



Used to define some constant value or values, including string literals, and place them in storage. 



G — i)' 

**- •» label ' 



(jT> 




O 



KDH 



cpression ■ 

string i . / T \ J 
literal | ^^J 



Item 


Description 


Range Restrictions 


label 


An identifier for the constant 


see "Symbols" 


value 


An expression that can be evaluated in pass 1 


-2 31 thru2 31 -l 


string literal 


A string of characters 


The instruction must 
be contained on one 
line 



Semantics 

Size suffixes may be used to specify the units of storage into which the values will be justified for 
storage. In the case of string literals, the amount of storage needed will be determined by the 
Assembler and each character will be assigned into a unit. 

The ".D" suffix is supported only for the MC68881 floating-point math co-processor. 



DECIMAL 



Causes addresses in the listing to be printed inn decimal rather than in hex notation. 



C DECIMAL j-*-\ 
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DEF 



Defines a label or list of labels as entry points for other modules. 



GEH 




label 



-H 



Item 


Description 


Range Restrictions 


label 


An entry point identifier 


see "Symbols" 



DS 



Reserves storage space. 



^-*- label ' 




KZP 



Item 


Description 


Range Restrictions 


label 
number 


An identifier for the data space 

An expression that can be evaluated in pass 1 


see "Symbols" 
thru 2 31 - 1 



Semantics 

The units of space are specified by the size suffix. The number of units is determined by the 
expression. 

The ".S", ".D", ".X", and ".P" are supported only for the MC68881 floating-point math co- 
processor. 
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END 



Indicates the end of the assembly. This should be the last line of the assembly. 



C end J-H 



EQU 



Assigns the value and attribute (absolute or relative) of the expression to the label. 



label 


— *-( EQU J—»- 


sxpression 


-H 


Item 


Desci 


iption 


label 
value 




An identifier 

An expression that can be evaluated in pass 1 



Range Restrictions 



see "Symbols" 
-2 31 thru2 31 -l 



INCLUDE 



Specifies a file to be merged into the assembly at the point where the instruction is located. The 
'.TEXT' suffix will be automatically appended to the file name. The INCLUDEd file may not contain 
another INCLUDE. 



mncludeV-*- 



file name 
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LLEN 



Used to specify the line length (column width) of your printer. 



f LLEN j-+- 



length 



LIST 



Turns the printer listing back on. You must have requested a listing when the Assembler was 
initiated for this to have an effect. LIST is used with NOLIST to exclude blocks of text from the 
listing. 



Q LIST )-h 
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LMODE 



Specifies a symbol or list of symbols to be accessed using long absolute addressing mode. Overrides 
short addressing and PC-relative mode implications of REFR, ORG, and RORG. 



( LMODE \ 



Item 



L 




symbol 



-H 



symbol 



Description 



A location identifier 



Range Restrictions 



see "Symbols" 



LPRINT 



(Default) Causes all output from DC statements to be printed. (See SPRINT) 

M.PRINT J~*-i 
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MNAME 



Used to assign a name to an Assembler module. The default is to assign the file name to the 
module. 



(mname j— *- 



module name 



NOLIST 

Turns off the listing until a LIST is encountered. 

C NOLIST J— H 



Requests that no object code be produced. 
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NOOBJ 



(noobj\-h 



Inhibits the listing of the symbol table at the end of the program. 



(nosymsY-m 



NOSYMS 
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ORG 



Specifies an absolute origin. When used with the ".L" option, it forces long mode addressing for 
forward and external references. Otherwise short absolute addressing mode is implied. 



C ORG J- 



absolute 
origin 



Item 


Description 


Range Restrictions 


absolute origin 


A numeric expression that can be evaluated in pass 1 


-2 31 thru2 31 -l 



PAGE 



Advances listing to top of next page. This command will not be printed on the listing. 



C PAGE V*H 
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REFA 



Defines a symbol or list of symbols as external and absolute references. The size of the effective 
address is implied by the ORG statement. 



r~Q> 



C REFA J 



symbol 



Item 


Description 


Range Restrictions 


symbol 


A location identifier 


see "Symbols" 



REFR 



Defines a symbol or list of symbols as external and PC relative references. 



C REFR J *-*■ 



symbol 



Item 


Description 


Range Restrictions 


symbol 


A location identifier 


see "Symbols" 
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RMODE 



Specifies a symbol or list of symbols for access using PC-relative addressing. Overrides all other 
addressing mode specifications. 



f rmode j 




symbol 



-H 



Item 


Description 


Range Restrictions 


symbol 


A location identifier 


see "Symbols" 



RORG 



Sets a relocatable origin. Using the 'L' option, forces long absolute addressing mode for forward 
and external references. Otherwise, PC-relative addressing mode is implied for forward references 
and short absolute addressing mode for REFA symbols. 



C RORG j- 



K 



ST 



relocatable 
origin 



Item 


Description 


Range Restrictions 


relocatable origin 


a numeric expression that can be evaluated in pass 1 


-2 31 thru2 31 -l 
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SMODE 



Specifies a symbol or list of symbols to be accessed using short absolute addressing mode. Over- 
rides all other addressing mode specifications. 



Tsmode\ 



L 



-©■ 



symbol 



-H 



Item 


Description 


Range Restrictions 


symbol 


A location identifier 


see "Symbols" 



SPC 



Directs the assembler to generate the specified number of blank lines. Used to separate blocks of 
code or blocks of comments on the listing. 



f spc V-»- 



number of 
blank lines 



SPRINT 



Print only the first line of output for the DC statements. Otherwise, each word used to store the 
constant is printed. 



(sprint j- h 
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SRC 



Used to specify the IMPORT text information which the Compiler needs when importing the 
module. Use one SRC for each line of IMPORT text, (see programming section) 



f SRC j—»~ 



line of 
export text 



START 



Specifies a start location for execution of the main program. Use only in the main program. 



(start j—+- 



start 
location 



Item 


Description 


Range Restrictions 


start location 


An integer numeric or symbolic expression 


-2 31 thru2 31 -l 



TTL 



Specifies a title to appear on each page of the assembler listing. 



(KH 



page title 
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The Examples 

Listings of the two programs and two modules are given here and also have been provided on the 
documentation disc (DOC:). On the disc they are provided in source and object form. The file 
(ASMB-P1) imports the file (ASMB-M1). These are both Pascal files. The Pascal file (ASMB_P2) 
imports the Assembler language file (ASMB_M2). 

If you want to see them work, you must either use the Librarian to link the modules to the 
programs, P-load the modules, or put the modules in the current System Library. You can then 
execute the two programs. 



The Sample Pascal Programs 

This Program Imports the Pascal Module 

{search '«3: ASMB_M1 

ProSram test ( input tout put ) i 

Impa rt simple! 

war iiJtK : reci 

be Si n 

initialize! 

i. ii : = 1 i i . iZ:=2i 

J . i 1 : =3 5 J. iZ: =4i 

add ( i t J ik ) i 

writelMK.il >K. iZ) 
end. 



This Program Imports the Assembly Module 



*search '«3 : ASMB_MZ 

Program test ( input toutput ) > 

Impo rt simpl eZ i 

war itJtK : reci 

be Sin 

initialize! 

i . i 1 : = 1 ! i.i2:=2i 

j. il :=3i J. iZ:=4i 

ad d ( i > J iK ) i 

writelMk. il »K. i2) 
end . 
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The Sample Pascal Module 



$ s y s p r o S $ ( * t o enable try-recouer*) 

module simple! 
export 
tv-pe 

rec = record 

il: integer! 
i2: int e Se r i 
end ! 
const 

zero = rec [ i 1 :0 .i2:0] ! 
v a r 

lastresult: rec! 

procedure initialize! 

procedure add (a>b: rec! war out: rec)! 

implement 
ua r 

sum : rec ! 

procedure initialize! 

b e S i n sum := zero end! 

function partadd (xix: inteSer): inteSer! 
ua r temp : inteSer! 
be Sin 

t emp : = x + y i 

if temp < then escape(lOO)! 

partadd := temp! 
end! <*partadd*> 

procedure add (a.b: rec! war out! rec)! 
b e si n 
t rv 

lastresult.il := partadd(a. ilib.il)! 
last result . i2 := pa rt add ( a . i 2 > b . i2 ) ! 
5um.il : = sum . i 1 + 1 ast resul t . i 1 ! 
sum.i2 := sum . i 2+ 1 as t resul t . i 2 ! 
out : = lastresult! 
recover 

if escapecode = 100 

then lastresult := zero 
else escape ( escapecode ) ! 
end! <#add#) 

end . 



The Disassembly of the Module 
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Librarian CReu. 2.0 19-Oct-B23 



19-Oot-BZ 



7:14 



paie i 



MODULE SIMPLE Created 

NOTICE: (none) 

Produced by Pascal Compiler 
Revision number 2 
Directory size 172 bytes 
Module size 3072 bytes 
Module NOT executable 



B-0ct-82 
of 20-Sep-82 



Code base 








Size 


254 bytes 








Global 


base 








Size 


1G bytes 








EXT 


blocK 


5 


S 


ize 


20 bytes 








DEF 


blocK 


3 


S 


i ze 


114 bytes 








EXPORT 


blocK 


1 


S 


ize 


192 bytes 








The re are 




1 


TEXT records 










TEXT RECORD » 






1 


of 'SIMPLE': 










TEXT start bl 


ocK 


2 




Size 


254 bytes 








REF start bl 


ocK 


4 




Size 


42 bytes 








LOAD address 


Rb 


ase 

















0000 








dc . w 


or dc . b tO 


o r 


dc 


b ' 


2 


0000 








dew 


or dc . b 0(0 


o r 


dc 


b ' 


4 


0000 








dew 


or dc . b tO 


o r 


d c 


b ' ' 


B 


0000 








dew 


or dc . b OtO 


o r 


dc 


b ' 


8 


0000 








dew 


or dc . b 0(0 


o r 


dc 


b ' 
















.INITIAL 


.IZE 


10 


4E41 


0000 






t rap »1 .*0 






14 


4CBA 
FFEE 


OFOO 






mouem.w Rbase 


( a0-a3 








20 


48AD 
FFFO 


OFOO 






MDveniiU a0-a3 


(Gbase-16(a5) 








2B 


4E5E 








unlK aB 










28 


4E75 








rts 










30 


0000 








dew 


or deb 0(0 


o r 


dc 


.b ' 


32 


4E41 


FFFC 






t rap *1 t*-4 










3G 


202E 


OOOC 






moue.l 12 (aB) 


(dO 








40 


DOAE 


0008 






add. 1 8(a6) idO 








an 


4E7G 








t rapv 










46 


2D40 


FFFC 






moue.l d0»-4( 


aG) 








50 


4AAE 


FFFC 






tst.l -4(aB) 










54 


BCOO 


OOOA 






bJe Rbase+BB 










58 


3B7C 


0064 






moue.w #100 .SYSGLOBALS-2 ( a5 ) 










FFFE 


















B4 


4E4A 








trap «10 










GB 


2DBE 
0010 


FFFC 






moue.l -4(aB> 


(lB(aG) 








72 


4E5E 








unlK a6 










74 


205F 








mouea. 1 ( sp)+ 


.aO 








7B 


504F 








addq . w *8 i sp 










78 


4ED0 








jmp ( aO) 










BO 


0000 








dew 


or d c . b 0(0 


o r 


dc 


.b ' 
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Lib 


ra ri an 


[Rev. 2 




82 


4E41 


FFFO 




86 


206E 


0010 




90 


2D58 


FFFO 




9a 


2D50 


FFF4 




98 


20GE 


OOOC 




102 


2D58 


FFF8 




108 


2D50 


FFFC 




110 


2F2D 


FFFG 




114 


2F0E 






118 


487A 


005A 




120 


2B4F 


FFF6 




124 


598F 






128 


2F2E 


FFFO 




130 


2F2E 


FFF8 




134 


4EBA 


FF98 




138 


2B5F 


FFFB 




142 


598F 






144 


2F2E 


FFF4 




148 


2F2E 


FFFC 




152 


4EBA 


FF8B 




15G 


2B5F 


FFFC 




ISO 


202D 


FFF8 




184 


D1AD 


FFFO 




1GB 


4E7G 






170 


202D 


FFFC 




174 


D1AD 


FFF4 




178 


4E76 






180 


20GE 


0008 




184 


4CAD 
FFF8 


1E00 




190 


4890 


1E00 




194 


2BBF 
FFFG 


0008 




200 


DEFC 


OOOC 




204 


4EFA 


0024 




208 


2C5F 






210 


2B5F 


FFFG 




214 


70G4 






218 


B06D 


FFFE 




220 


GGOO 


0012 




224 


4CBA 
FFIC 


OFOO 




230 


48AD 

FFF8 


OFOO 




238 


6000 


0004 




240 


4E4A 






242 


4E5E 






244 


205F 






24G 


DEFC 


OOOC 




250 


4ED0 






252 


4E75 





2.0 l.g-0ct-82] 19-0ct-B2 9: 7:14 

--------------- SIMPLE-ADD 



trap *1 i»-16 

mo vea . 1 1G ( aB ) iaO 

move . 1 ( aO)+ .-1G( aG) 

move. 1 ( aO) .-12(a6) 

movea. 1 12( aG) iaO 

move .1 ( aO)+ t-8( aG) 

move . 1 ( aO) i-4( aG) 

move. 1 SYSGLOBALS-lO(aS) t-(sp) 

move . 1 aGi-(sp) 

pea Rbase+208 

move.l sp »SYSGL0BAL8-10(a5) 

subq.l *4»5P 

move.l - 16 ( aG ) »- ( sp ) 

move.l -B(aG)i-tsp) 

Jsr Rbase+32 

move.l (sp)+iGbase-8(a5) 

subq.l »4tsp 

move . 1 -12(aB)»-(sp) 

move.l -4(aS)i-(sp) 

Jsr Rbase+32 

move.l (sp)+»Gbase-4(a5) 

move. 1 Gbase-8(a5) ,dO 

add.l dO ,Gbase-18(a5) 

t r a p v 

move.l Gbase-4(a5) > d 

add.l dO -Gbase-12(a5) 

t r a p v 

movea . 1 8 ( aB ) »aO 

movem.w Gbase-B ( a5 ) .al -a4 

mo vem . w al -a4 > ( aO ) 

move. 1 8( sp) .SYSGLOBALS- 1 ( a5 ) 

adda.u »12 .sp 

jmp Rbase+242 

movea. 1 ( s p ) + . a 6 

move , 1 (sp)+ .SYSGLOBALS- 10 (a5) 

moveq *100idO 

chp.u SYSGLQBALS-2( a5) .dO 

brie Rbase+240 

movem.w Rbase>aO-a3 

movem.w a0-a3 >Gbase-8 ( a5 ) 

bra Rbase+242 

trap * 1 

unlK aG 

movea. 1 ( s p ) + t a 

adda.w * 1 2 . s p 

Jmp ( aO ) 

dew 20085 or dc.b 78.117 or d c . b 'Nu' 



The Assembler 267 



The Assembly Language Module 



mname simple2 

s re module s impl e2 i 

s re export 

5 r e type 

s re rec = 

s re i 1 

s re i2 

s re end i 

s re const 

s re zero = 

s re war 

sre lastresult ; rec! 

sre procedure initialize! 

sre procedure addlaib : reci 

sre u a r out : rec ) ! 

sre end! 



record 

: i n t e S e r ! 

: inte ie r ! 



r e c [ i 1 : » i 2 : 3 



com s imp 1 e2 i - 16 

def simple 2_ add 

def simple2_ini t ial i ze 

def s impl e2_ze ro is impl e2_s impl e2 

refa svsslobals 



lastresult 
1 as t resul t_i 1 
lastresult_i2 
sum 

sum_i 1 
s u m _ i 2 
escape code 
recowe r_rec 



eiu s imple2-B 

e i u simple2-8 

esu s imple2-4 

eiu simple2-lB (all are relative to a5) 

eiu s imple2- IB 

eiu s impl e2- 12 

eiu sysslobals-2 

e q u sysSlobals-10 



r o r 1 
si m pie 2_ zero del OiO 

simple2_initial ize trap *1 (stacK cheek) 

dc.w (no local space) 

movem.l s impl e2_ze ro i aO-al 

movem.l aO-al tsum ( a5 ) 



unlK a6 
rts 

simple2_partadd trap *1 
dc.w -4 



result 

x 

y 

re t_add r 



eiu IB 

e q u 12 

B1U 8 

B1U 4 



(all are relative to aB) 
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d y n _ 1 i n k eiy 
temp equ-4 

moue.l x(a6)id0 (temp:=x+y> 

add . 1 y ( aB) .dO 

t r a p u (ouerflow check) 

moue 4 1 dO tt emp ( aB ) 

tst.l temp(aG) (if temp<0) 

b Se past-escape 

move *100 .escapecode ( a5 ) 

trap *10 (then escape 100) 

past_escape moue.l t emp ( aG ) > re s u 1 1 ( aG ) 

* (partadd:=temp) 

mouea.l re t_add r ( a6 ) i aO 

u n 1 k a B 

a d d a . 1 * 1 2 > s p 

Jmp ( aO) 

simple2_add trap *1 (stack check) 
dc.w -1G (for par am copies) 

a_addr eiu 16 

b _ a d d r e i u 1 2 

out_addr e q u 8 

ret_addr2 eiu 4 

d y n _ 1 i n k 2 e q u (relative to aG) 

b_i2_copy e^u -4 

b_il_copy e q u -8 

a_i2_cop>- eiu -12 

a_il_copy eiu -IB 

mouea.l a_addr(aG)>aO (makinS local 
moue.l ( aO ) + ia_i l_c opy ( aB ) copies) 
moue.l ( aO ) i a_i 2_copy ( aG ) 
mouea.l b_add r ( aB ) • aO 
moue.l (aO)+tb_il_copy(aB) 
moue.l ( aO ) >b_i 2_co py ( aG ) 

moue.l recoue r_ rec ( a5 ) t- ( sp ) (TRY) 

moue.l aGi-(sp) 

pea re co v e r_ad d r 

moue.l sp » recoue r_ rec ( a5 ) 

subq.l «4tsp (calling partadd) 

moue.l a_il_copy(aG)i-(sp) 

moue.l b_il_copy(aG) » - ( s p ) 

Jsr s impl e2_pa rtadd 

moue.l (sp)+ilastresult_il(a5) 

sub i.l #4)SP (call-ins partadd) 
moue.l a_i2_copy ( aG ) >- ( sp ) 
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move.l b_i2_copy ( a6> i- < sp) 

jsr s impl e2_pa rt add 

moue.l ( 5P ) + t last resul t_i2 ( a5 ) 

mave.l 1 ast resul t_i 1 ( a5 ) tdO (sum:= 

add.l dO isuM.i 1 ( a5 ) sum+1 ast resul t ) 

t rapu 

moue.l 1 as t re su 1 t_i2 < a5 ) tdO 

add.l dO >sum_i2( a5) 

t rapu 

mouea.l o ut_ad d r ( aB ) >a0 

m o u e m . 1 lastresult(a5) t a 1 - a 2 

mouem.l al-aZt(aO) ( out : = 1 as t resul t ) 

moue.l 8<5P) trecauer_rec(a5) 

adda.l *12 f sp (end of TRY) 

j m p past_recouer 

recauE r_add r mouea.l (sp)+»a6 (RECOVER) 
moue.l ( sp ) + i recoue r_ rec ( a5 ) 
moueq *100»dO (if esc apeco de= 100 ) 
cmp.w escapecode(a5) idO 
bine svs_e r ro r 
mo vem i 1 simple2_zeroiaO-al 

* (thenlastresult:=0) 

mouem.l aO- al 1 1 as t res ul t ( a5 ) 



bra past.recouer 
s y s_e r ro r trap »1 

past.recouer unlK aB 
mouea.l (sp)+>aO 
adda.l *12 >sp 



(else escape ) 



J m p ( a ) 
simple2_simple2 
end 



(initialization body) 



*** B8000 ASSEMBLER SYMBOL TABLE DUMP *** 



EXTERNAL SYMBOLS 



SYMBOL 


TYPE 


DEF 


VALUE 


SIMPLE2 


ABS 


19 


00000001 


SYSGLOBALS 


ABS 


25 


00000002 



INTERNAL SYMBOLS 



SYMBOL 


TYPE 


DEF 


EQU SYM 


AO 


AREG 







Al 


AREG 







A2 


AREG 







A3 


AREG 







A4 


AREG 
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Introduction 

It may seem obvious that the Librarian's purpose is to manage libraries. However, all the things that 
it can do to fulfill this responsibility may not be as obvious. This chapter will help to put all of the 
Librarian's capabilities into perspective. The chapter first describes libraries and object modules, 
providing some relevant background information that will help you to understand the Librarian 
operations described in the latter sections of the chapter. 

Here is a brief overview of the operations you can perform with the Librarian: 

• Add object modules to or remove them from libraries. For instance, you can add object 
modules to the System Library so that the modules will be found and loaded automatically 
when any program that imports them is loaded for execution. 

• Link the directories of the object modules in a library file. This operation reduces the file's size. 

• Obtain detailed information about the object modules in a library file. For instance, you can 
unassemble a compiled Pascal object file and get the Assembler language object code. The 
Librarian can disassemble all instructions for the MC68000 family of processors, as well as 
MC68881 math co-processor instructions. 

• Create new system Boot files. This operation is used to create files that are found and loaded 
by the Boot ROM and in turn load a system. 

Let's look more closely at library files, what is in them, and how to use them. 

Prerequisites 

This chapter presents simple examples of user modules and libraries. If you find that you want more 
information about modules as you read this chapter, read the sections of the Compiler and 
Assembler chapters that describe modules. 

If you are going to be using the Librarian for purposes other than adding modules to and removing 
them from the System Library (usually LIBRARY) or Initialization Library (BOOT:INITLIB), then 
you should also be familiar with the concepts presented in the Assembler chapter. 
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Library Overview 



This section presents some important terms and concepts you will need to know in order to 
understand libraries. It will help you see when and why you will need to use the Librarian. 

Modules and Libraries 

Libraries are object files. They contain zero or more object modules. Object modules are the 
product of the Compiler or Assembler 1 . For instance, compiling a Pascal source module generates 
an object module which is placed in an object file. This file is actually a library, because it contains 
an object module. 

An object file is composed of a directory of the module(s) that it contains, followed by the object 
modules themselves. Here is a pictorial representation of an object file. 

OBJECT FILE 



"\ 



Library Directory 


Object Module Directory 


Define Source 


Ext Table 


Def Table 


Text Record 


Ref Tables 


• 
• 
• 


Text Record 


Ref Tables 



\ Object 



Module 



V 



The terms Define Source, Ext Table, and so forth are defined in the Glossary of Object Code 
Terminology at the end of the chapter. 

What the Librarian Does 

The Librarian's purpose is to manage object modules. The Librarian can also produce object files; 
however, these files consist of object modules produced by the Compiler or Assembler. It can 
create library files and add modules to them or remove modules from them. The intent of these 
libraries is to provide a convenient location to store object modules. The following drawing shows 
the relationship of object modules in an object file (library): 



1 Complete descriptions of how to produce and use Pascal and Assembler modules are provided in the Compiler and Assembler chapters. 
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OBJECT FILE 



Library Directory 


Object Module Directory 


• • • 


Object Module Directory 


Define Source 


Define Source 


Ext Table 


Ext Table 


Def Table 


Def Table 


Text Record 
Ref Tables 


Text Record 


Ref Tables 



Text Record 
Ref Tables 



Text Record 
Ref Tables 



Example Modules 

For this example, we will be using three example library modules provided on the DOC: disc 
shipped with your system. One contains a compiled program (PROG_l.CODE), and the other two 
contain compiled modules (MOD_2.CODE and MOD_3.CODE). 

The DOC: disc also contains the source versions of these modules. Although this chapter will only 
be dealing specifically with the object versions, it is a good learning experience to compile the 
source versions to see how the Compiler deals with imported modules. One method is briefly 
outlined in the next section. 

Here are source listings and brief explanations of each of the example modules. 

Source Listing of PROG_l.CODE 



PROGRAM Proarairtunet OUTPUT) ! 

IMPORT ModuleTwoi 

BEGIN 

WRITELNi 

WRITELNi 

WRITELN ( '*#***********»* ProSramOne *****#*****»***'); 

TwoL in es ! 

WRITELN( '**#******♦♦#*** ProSramOrce ♦****♦****##***')! 



END, 
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The example program imports ModuleTwo, which declared the procedure named TwoLines. Here 
is the source of ModuleTwo, which was compiled and stored in the library (object-code) file named 
MOD_2.CODE. 

Source Listing of MOD_2.CODE 

MODULE ModuleTwo i 

IMPORT ModuleThree! 

EXPORT 

PROCEDURE TwoLines i 

IMPLEMENT 

PROCEDURE TwoLines! 
BEGIN 

WRITELNI'I came from ModuleTwo and brouSht this:')! 

Th i rdLine ! 
END! 

END. 

ModuleTwo exports procedure TwoLines, which is used by ProgramOne. It also imports Mod- 
uleThree, which declares procedure ThirdLine and is in the library (object-code) file named MOD_ 
3. CODE. 

Source Listing of MOD_3.CODE 

MODULE ModuleThree! 

EXPORT 

PROCEDURE ThirdLine! 

IMPLEMENT 

PROCEDURE ThirdLine! 
BEGIN 

WRITELN('I came from ModuleThree')! 
END! 

END. 

This module exports procedure ThirdLine, which is imported by ModuleTwo. Notice that it does 
not import any modules. 

Here are the results of running the program. 

***#*******###* PrasramOne *************** 
I came from ModuleTwo and brought this: 
I came from ModuleThree 
*************** PrasframOne *************** 
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Here is what happens when you run ProgramOne. First, ProgramOne prints two blank lines and 
then the line of asterisks that contains its name. The procedure TwoLines, imported from Module- 
Two, is then called; it prints the message: I came from ModuleTwo and brought this:. 
Procedure ThirdLine, imported from ModuleThree, is then called; it prints the message: 
I came from ModuleThree. Control is then returned to TwoLines and then to the program, 
which again prints out its name in asterisks. 

Let's take a look at what is needed in order for you to compile and run the program. 

Compiling and Running the Example Program 

When a program (or module) imports modules, the imported modules must be accessible at two 
times: 

• When the program is compiled. 

• When the program is loaded and run. 

Let's take a look at what happens at these two times. 

How the Compiler Finds Imported Modules 

At compile time, the Compiler searches for each module imported by the source program (or 
module); more specifically, it searches to find each module's "interface text." Here is the order of 
the places where the Compiler looks in search of interface text: 

1. In the source text being compiled. (The source text of modules and programs can be 
combined into one source file, as long as the modules precede the program and are in proper 
sequence. ) 

2. In object files specified in a SEARCH Compiler option. 

3. In the object file currently designated as the System Library. 

(A module's interface text consists of the MODULE name, the IMPORT section, if present, and 
EXPORT section; these sections are part of the object module produced when the module was 
compiled or assembled. See the subsequent section called Getting Detailed Object File Information 
and the Compiler or Assembler chapters for a more complete description of interface text. ) 
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Here is a strategy (and the method actually used) for compiling these source modules and program. 
(Note that you will be learning these Librarian operations in the subsequent examples given in this 
chapter, so you will probably want to perform this compilation exercise after working through the 
examples using the object modules and program). 

1. Compile ModuleThree first (MOD_3.TEXT); call it MOD_3.CODE for simplicity. Since this 
module does not import any others, it will be compiled with no need to search for any 
imported module's interface text. 

2. Use the Librarian to add the resultant object module (MOD_3.CODE) to the library file 
currently designated as the System Library. (Actually, you will be creating a new library into 
which you will place ModuleThree and the modules in the current System Library; this type 
of operation is subsequently explained in this chapter. ) 

3. After merging these two libraries (into a third new library), you will need to do one of two 
things: use the What command to make the resultant library the System Library; or use the 
Filer to change the resultant library's name back to the name of the current System Library. 

4. Next, compile ModuleTwo (MOD_2.TEXT); call it MOD_2.CODE. The external references 
to ModuleThree will be resolved when the Compiler finds the object ModuleThree in the 
System Library. 

5. Then place this compiled module in the System Library as in steps 2 and 3. 

6. Compile the program (PROG_l.TEXT). Since both object modules upon which this prog- 
ram depends are in the System Library, they will be accessed automatically by the Compiler 
when the program is compiled. 

7. Run the program. The loader automatically looks in the System Library in order to resolve 
the external references; it loads the modules required to complete the program (in this case, 
ModuleTwo and ModuleThree). 

Since the program and modules have already been compiled and the object files placed on the 
DOC: disc, we will not discuss other alternatives of making the source files accessible to the 
Compiler. (However, you are again encouraged to do this after learning how to use the Librarian.) 

Let's look now at how the loader finds imported object modules when the program is to be loaded 
for execution. 
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How the Loader Finds Imported Modules 

Since a compiled program contains no record of where the Compiler found the imported modules, 
the loader must find the imported object modules at load time. Here is the order of the places where 
the loader looks: 

1. Modules that are part of the object file being loaded. 

2. In modules already P-loaded in memory, which includes all INITLIB and Operating System 
modules. (The loader searches for these modules in reverse order to which they were 
P-loaded; in other words, the most-recently loaded modules are searched first.) 

3. In the current System Library file. 

In order to make all imported modules part of the object file that uses them (alternative 1 above), 
you have two choices: 

• Combine the source modules into one source file (and compile it). You can use the Editor to 
add each imported module's source file to the source program. You can also use an INCLUDE 
Compiler option in the source program to include each imported module's source file in the 
compilation of the program. 

• Combine the object modules into one object file. Use the Librarian to combine the program 
and imported modules into one object file; you can optionally Link the modules to save space. 

With both of these methods, only the file containing the program need be loaded; and when the 
program is finished, the memory used by the modules can be reclaimed for other purposes. With 
P-loaded modules, this is not possible (without re-booting). 

If you want to P-load modules to make them accessible to the loader, you will only need to P-load 
all modules which are not in one of the three places stated above. In the example modules already 
given, ProgramOne imports ModuleTwo, and ModuleTwo imports ModuleThree. In the second 
example that follows, you will be creating a library that contains these two modules and then 
P-loading the library. (You can alternatively P-load MOD_3.CODE and MOD_2.CODE, in that 
order, which does not require use of the Librarian.) The loader will then be able to link the modules 
contained in the library to any program that imports them at execution time. 

In general, the most convenient way to use modules is to place them in the file that is currently 
designated as the "System Library," which is the third alternative shown above. (The default 
System Library is the file named "LIBRARY" found on the system volume at power-up. You can 
also change it with the What command and the Main Command Level.) This is probably the most 
common reason for using the Librarian. In the first example that follows, you will add modules 
ModuleTwo and ModuleThree to the LIBRARY file and then run the program. 

Subsequent tutorials also describe unassembling these library files and creating system Boot files. 
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Entering the Librarian 

The Librarian is provided on the ACCESS: disc shipped with the system. To use the Librarian, you 
will first need to put it on-line: either place the disc labeled ACCESS: in a drive, or copy the 
LIBRARIAN file to another location (such as a hard disc) and use the What command (at the Main 
Comm and Level) to specify this copy as the system Librarian. After doing either of these, pressing 
( L ) directs the system to load and execute the Librarian program. 

Here is the Librarian's main prompt: 



Li b ra ri an [Rev , 



3.0 15-Apr-B4] 



15-Apr-B4 



8: 11 :5B 



Quit 

P Printout OFF PR INTER : LI NK . ASC 

Output file: (none) 

B write to Boot disk 

H file Header maximum size: 



Input file: (none) 



38 



Copyrisht 1984 Hewlett-Packard Company, 
command? 



The commands shown on the left-hand side of the screen are invoked by pressing the correspond- 
ing key. You will see how to use all of them in the following tutorial discussions. All commands are 
summarized in the Librarian Command Reference. 
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Setting Up Mass Storage 

You will often need two on-line mass storage volumes when using the Librarian. If you only have 
one volume in your system, you may need to set up a memory volume. This discusson tells why 
two volumes may be needed and then outlines how to estimate the size of the volumes required. 

When you combine the object modules in two libraries using the Librarian, you actually create a 
third (new) library and then copy into it the desired modules from the other two libraries. For 
instance, suppose that you want to add the CONFIG:RS232 module to the BOOT:INITLIB library 
file. You will first create a new library, and then add the existing INITLIB modules and the RS232 
module to this new library. This new library must nor be taken off-line during the entire process. 

Thus, two separate volumes are often necessary for these two reasons: 

• The sum of all source libraries plus the new destination library often exceeds the capacity of 
one volume. 

• The destination volume must not be taken off-line during this entire operation. 

Continuing with the preceding example, suppose that you have only one mini-disc drive on-line 
(the capacity is approximately 1050 sectors). The operation cannot usually be completed, because 
one mini disc is not large enough to contain the modules in the INITLIB file (let's assume 750 
sectors), the RS232 module (approximately 25 sectors), and the new INITLIB file (roughly the sum 
of 750 and 25 sectors). You will need two volumes for the process. 

If you don't have two disc drives (or one with sufficient space), you can create a memory volume. It 
is usually more convenient to use the memory volume as the destination volume. In this case, you 
could create one with a specified size of 400 blocks, or 200 Kbytes. (Remember that memory 
volume blocks are 512 bytes each, while mini-disc sectors are 256 bytes each.) See the Memvol 
command in the Overview chapter for more specific details on creating memory volumes. 

The following examples assume that either you have two disc volumes on-line or that you have 
created a memory volume of sufficient size. For these examples, a memory volume of 100 blocks is 
sufficient. 
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Creating Libraries of Object Modules 

To create libraries, you can combine either modules provided by HP or your own modules, or any 
combination of the two. Let's first look at adding modules to the System Library file. 

Adding Modules to the System Library 

A common way to use library modules is to add them to the current System Library file. Let's 
assume that it is the file named LIBRARY for present purposes, although you can change it to any 
file by using the What command at the Main Command Level. The procedure used to add modules 
to LIBRARY is very similar to that of storing modules in a user library, which is the next example. 

Here is a brief summary of the steps required: first, make a new library file, and copy into it all of the 
modules currently in LIBRARY; next, add ModuleThree and ModuleTwo to the new file (in this 
case the order of modules is arbitrary, since the loader will load them in the right order); then 
replace the LIBRARY file with this new library; execute the program, and the modules are loaded 
automatically for you. The actual procedure is given below. 



1. Invoke the Librarian. This is done by pressing ( L ) from the Main Command Level. (If the 
Librarian is not on-line, insert the ACCESS: disc and try again. Remove the ACCESS: disc 
once the Librarian has loaded. ) Now use the Librarian to create the new library. 

2. Put the SYSVOL: disc (or the one containi ng the LI BRARY file) in the #3 drive. Press ( I ) 
and then type «3:LIBRARY. and press (Return) or (ENTER) to enter the Input file. You must 
include a trailing period to prevent the Librarian from appending the * CODE suffix. 

When the Librarian finds the Input file, the display will show the name of the first module in 
the file. (You should see the module nam ed RN D if you have not yet modified the LIBRARY 
file. ) If you have a printer, you can press ( F ) to list all of the modules in the Input library. 

3. (For this example, we will assume that you are using unit #4 as the second volume; 
however, if the LIBRARY file is small enough, you can also put the new library file on drive 
#3. We will also assume that the destination volume has enough room for the new library 
file.) 



Press ( ) and enter »4:NEWLIB. as the Output file. Again, a trailing period prevents the 
i CODE suffix from being appended to the file name. If you are using a memory volume, use 
the unit number of the memory volume. 

(If you are using a disc, this disc must not be removed until you have finished creating the 
new NEWLIB file.) 



4. Press ( E ) to enter the Edit mode. You should now see this prompt (in the middle of the 
screen): 

F First module: RND 

U Until module: (end of file) 

5. You can now transf er all modules in the Input file to the Output file, including the last 
module, by pressing ( C ) (for Copy). 

6. When the preceding transfer is complete, press ( A ) to append a module to the NEWLIB 
Output file. The Librarian prompts with Input file:. Put the DOC: disc, or whichever 
disc now contains ModuleThree, in Unit #3 (not #4, which must not be removed). Enter 
*3 : M0D_3 as the Input file. 
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7. The Librarian now prompts with E nte r list of modules or = for all. Enter = 
for all. After ModuleThree has been transferred to the NEWLIB library, the Librarian 
prompts with A p p e n d done* < space > to c o n t i n u e . Press the spacebar to clear the 
prompt. 

Now use steps 6 and 7 again to copy ModuleTwo (in file MOD_2.CODE) into the NEWLIB 
file. 

8. Now that all modules have been added to the NEWLIB file, press ( S ) to stop editing and 
( K ) to keep the file. 



9. You should now verify that the modules were indeed copied to the Output file. Press ( I ) 
and enter »4 : NEWL I B . as the Input file. Press the spacebar r epeate dly to scan through the 
modules in the new library file. If you have a printer, press ( F ) to get a File Directory 
listing. 

10. If all modules are present, then press ( Q ) to Quit the Librarian. 

11. Now you have one of two options to make this library the System Library: you can use the 
What command at the Main Level to specify the file named NEWLIB (on the destination 
volume) to be the System Library; or you can replace the LIBRARY file on the SYSVOL: 
disc with this file. If you choose the second option, it is probably better to keep the current 
copy of LIBRARY on the disc; you should first Change its name to something like OLDLIB 
and then Filecopy the NEWLIB file onto the SYSVOL: disc, changing its name to LIBRARY. 

12. Make sure that the System Library file is on-line, and then eXecute or Run the program. 

As the program is loaded, the imported modules will also be loaded automatically. Here are the 
results of running the program. 

*************** ProSramOne *************** 
I came from ModuleTwo and brought this: 
I came from ModuleThree 
*************** ProsfrawOne *************** 

After the program has completed execution, the memory used by both program and modules can 
be used for other purposes. 

As you can see, the System Library is a special library of object modules that is automatically 
accessed by the linking loader at program execution time (and by the Compiler at compile time). 
Because of this automatic access, you do not need to use the Permanent-load command to access 
this library's contents. This library would normally store those modules often used in your prog- 
rams. Further descriptions of using HP-supplied libraries are given in the Pascal 3.0 Procedure 
Library and Pascal 3. Graphics Techniques manuals. 
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Making Your Own Library 

Since we created a library that contains the modules named ModuleTwo and ModuleThree in the 
preceding example, you already know what is required to make your own library. The only 
difference is that you will not be adding the current LIBRARY modules to your library. 

Here is a brief summary of the steps you will take in this example: first, create a new library with the 
Librarian and add the example modules ModuleTwo and ModuleThree to it (as with the last 
example, the order of modules is arbitrary; since they are in one file, the loader will take care of 
loading them in the proper order); P-load this library; and execute or run the program. A more 
detailed procedure follows. 



Note 

During the transfer process, you must not move the destination disc (the 
one that contains the Output file). 



1. From the Main Command Level, press ( L ) to enter the Librarian. Your screen should 
now display the Main Prompt for the Librarian. 

2. Put th e d estinati on disc in drive #4. Then press ( ] , and type »4:USERLIB and press 
( Return ) or (ENTER) to enter the Output file specification. 

3. Place the DOC: Disc into the #3: disc drive. Then press ( I 1 and enter *3 : M0D_3 as the 
Input file specification. You will see M0D_3, CODE displayed as the Input file. The first object 
module found in the object file, MODULETHREE, is also displayed. The computer is in 
Copying mode as shown by the word COPYING on the prompt. 

5. Transfer the object module MODULETHREE using the T command. Since MOD- 
ULETHREE is the only module in that file, the A command would have done the same job. 

6. Repeat steps 4 and 5 to name MOD_2 as the Input file and Transfer the object module 
MODULETWO into your new library. 

7. If you had other modules to transfer, you would repeat steps 4 and 5 as needed. 

8. Press ( K ) to Keep the new file on the destination volume. 

9. Press [ Q ) to Quit the Librarian and return to the Main Command Level. 

10. If you P-loaded these modules as you worked through the preceding example, then you 
need to re-boot in order to fully test your new library (to ensure that the modules P-loaded in 
the preceding example aren't accessed instead). 

11. Press ( P~) for the Permanent-load command. You will be prompted: 
Load what code file ? Enter *4 : USERL IB (you don't need a period if you didn't 
include one when you specified this file as the Output file). 

12. Now press ( X ) to eXecute ProgramOne. Answer the E x e c u t e what file? prompt 
by entering #3:PR0G_1 as the file specification. 

The results of the executed program are shown below. 

*************** ProsramOne *************** 
I came from ModuleTwo and brought this: 
I came from ModuleThree 
*************** P ro s ramOne *************** 
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As mentioned earlier, you could also have separately P-loaded ModuleThree and ModuleTwo, in 
that order, and then run the program. Or, as with the preceding example, you could also have 
added these modules to the System Library. You could also have used What at the Main Com- 
mand Level to specify this library as the System Library. The method you use depends on factors 
such as these: whether you are developing and testing the modules; whether you are also using 
other modules in the System Library; who will be using the modules; and so forth. 

Linking Object Files Together 

The Librarian permanently links modules together by combining their module directories into a 
single directory. To see this process in action, you will be linking the two example modules and the 
example program together. 

1. Put the ACCESS: disc in a drive and press ( L ) to run the Librarian. 

2. Put th e D OC: d isc in the #3 drive. Press ( ) , and then type *3:TEST_1 and press 
( Return ) or (ENTER) to enter the Output file specification. #3:TEST_l.CODE will be our linked 
library's name; *3:TESTl.C0DEis now displayed as the Output file. When an Output file is 
named, the menu replaces the B and H command prompts with the "L Link" prompt. The 
Librarian also enters the COPYING mode. 

3. Enter the LINKING mode by pressing ( L ) . This is the first step in the two-step linking 
process. Your screen now displays a new command prompt, as shown below. 



Li b ra r i an [Reu 



3.0 



15-Apr-B4] 



l-Jun-84 8:05:0B 



Q Quit 

P Printout OFF PRINTER : LINK . ASC 

Output file: 

C Copy 

N Name of new module: 

R Relocation base : 

G Global base: 

S Space for patches: 

D output Def table? 

X copyright notice: 



TEST_1.C0DE 

( none ) 





YES 



LINKING 



Input file: 



(none) 



command? 
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Press [ N ) and enter NEW NAME as the new module name. If you did not do this, the object 
module contained in the new object file, TEST_l.CODE, would be the module name of the 
first module transferred. To avoid confusion, use "NEWNAME". 



5. Press [ I ) and enter #3 : PRDG_ 1 as the Input file. (The ".CODE" suffix is automatically 
appended to the Input file's name.) PROG_l.CODE is now the Input file. 

6. Press ( A ) to transfer all object modules contained in PROG -l.CODE into TEST_ 
l.CODE. Since PROG_l.CODE contains only one module, ( T ) would have done the 
same job. 

7. Repeat steps 5 and 6 to transfer MOD_2.CODE and MOD_3.CODE. When all files are 
transferred, final linking must be done. 

8. Press ( L ) to complete the linking process. This is the second step in the linking process. 
Remember that all object modules must be on-line when you complete the linking process. 

9. Press ( K ) to Keep the new file, and press ( Q ) to Quit the Librarian and return to the 
Main Command Level. 

To see that everything works, execute your new program. From the Main Command Prompt press 
( X ) , and then enter TEST_1 as the file specification. The ".CODE" is automatically added to 
the file name. Your screen should now display the the following: 

*************** p ro 3 ramOne *************** 

I came from Module_2 and brought 

I camd from Module_3 

*************** ProSramQne *************** 

The benefit gained over merely combining modules into one library is that linking modules together 
reduces the amount of space required to store the library. 

Subtle Points about Linking 

There are several subtle side effects that occur when modules are linked that should be discussed 
here. 

• When you link object modules, the interface text is removed. Thus, linked modules cannot be 
searched by the Compiler when it is attempting to satisfy IMPORT statements; however, these 
modules can be used by other modules at load time by P-loading them or placing them in the 
System Library. (Remember that you can also keep a copy of the unlinked object module 
which can, of course, be imported by other modules at compile time. ) 

• The linking process always produces relocatable object code. This code has been relocated to 
the values specified by Global base and Relocatable base, but it will be relocated again when it 
is loaded for execution. For this reason, you don't need to specify Global base and Relocatable 
base - just leave them zero. 
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• If two or more programs are linked together into one object file, the resultant file contains code 
with only one start address (rather than the two that you began with). Contrast this to the 
situation in which you put two programs in an object file; when this file is executed, the two 
programs get executed separately in the order encountered in the file. This is the reason that 
you cannot link the INITLIB modules together; it is actually a set of programs and modules in a 
library file. 

• After linking, most programs will still have unsatisfied external references (such as calls to the 
File System read and write routines). These unsatisfied references do not cause error mes- 
sages; they are satisfied by the linking loader as the program is prepared for execution. These 
system routines are not part of the compiled or linked program; rather, the entire operating 
system looks to the linking loader like a group of P-loaded user libraries. 

Summary of Linking Object Files 

Note 

All input modules must remain on-line for the duration of steps 6 
through 9. The output file must be on-line for steps 3 thru 10. 



1. Enter the Librarian. 

2. Be sure the disc containing the file to be linked is in the appropiate disc drive. 

3. Specify an Output file name. 

4. Press ( L ) to begin the linking process 

5. Name the new module with the Name Command. 

6. Specify the Input file containing the modules you want to link. 

7. Transfer only those files you want into the new Output file using the All and Transfer 
commands. 

8. Repeat steps 6 and 7 until all files are transferred. 



9. Press ( L ) to complete the Linking process. 

10. Press ( K ) to keep your output file. 

11. Press ( Q ) to quit the Librarian 
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Getting Detailed Object File Information 

Let's unassemble the file MOD J2. CODE to see how the Librarian provides detailed information 
about a code file. It is best to have a printer on-line while unassembling; however, if you don't, you 
can declare a Printout file as described in the following procedure. 

1. The Librarian is on the ACCESS: disc shipped with your system. To access the Librarian, 
you will need to put this disc on -line, or copy the file to a disc that is on-line, or P-load the file. 
After the file is on-line, press [ L ) (at the Main Command Level) to load the Librarian 
subsystem into the computer. 

2. If you don't have a printe r on-lin e, then you must specify a file to which the unassembled 
information is sent. Press [ P ) (for Printout) and enter a file specification; if no suffix or 
trailing period is included, then ".TEXT" is appended to the file name. The screen will be 
updated to show that the printout device is ON and that it is the file you specified. 

3. Press ( I ] and enter »3 : M0D_2 as the Input file. No Output file is needed. 

4. Press ( U ) to get into the Unassemble mode. 

Your screen should now show the Librarian Unassemble menu. 



Librarian [Rev. 3.0 



15-Apr-843 



l-Jun-84 9:45:02 



Quit 

S Stop unassembling 

T print impo rt Text 

E print Ext table 

D print Def table 

A unassemble all (Assembler conventions) 

C unassemble all (Compiler conventions) 

P PC ranSe (Assembler conventions) 

L Line ransfe (Compiler conventions) 



unassemb 1 e option? 



When the first command key is pressed, an information header is printed along with the desired 
information. This header is printed only this one time. An internal counter keeps track of the line 
count and prints a page heading at the top of every new page. If you change the placement of the 
printer paper, you may waste some paper when the counter sends a form-feed to the printer. When 
you quit, a final form-feed is sent to the printer automatically. 
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The Text and Table Commands 

Use these commands to obtain Interface Text and REF and DEF tables of modules. 

The Prin t Impo rt (or Interface) Text Command 

Pressing ( T ) prints the interface text (DEFINE SOURCE) of the module, if any. In a compiled 
module, the DEFINE SOURCE portion consists of the text in the MODULE, IMPORT (if present), 
and EXPORT declarations; in an assembled module, this text consists of the lines containing the 
SRC pseudo op. (Note that any comments and indentation have been removed. ) 

Librarian [Reu. 3.0 15-Apr-S41 23-Apr-84 7: B:5i paSe 1 

MODULE MODULETWD Created 23-Apr-84 
NOTICE: (none) 

Produced by Pascal Compiler of 23-Apr-84 

Reu i si on numbe r 3 

Directory size 174 bytes 

Module size 3072 bytes 

Module NOT executable 

Code base Size 104 bytes 

Global base Size bytes 

EXT blocK 5 Size 72 bytes 

DEF block 3 Size 90 bytes 

EXPORT blocK 1 Size 74 bytes 

There are 1 TEXT records 

DEFINE SOURCE of 'MODULETWO': 

MODULE MODULETWO! 
IMPORT ModuleThreei 

EXPORT 

PROCEDURE TuoLinesi 

end; 

The Prin t EXT Table Command 

Pressing ( E ) prints the table of External symbols the module references. Detailed information on 
the EXT table may be found later in this chapter. 

EXT table of 'MODULETWO': 

FS.FWRITELN 
FS.FWRITEPAOC 
MODULETHREE_.THIRDL.INE 
SYSGLOBALS 

The Prin t DEF Table Command 

Pressing ( D ) prints the table of symbols the module itself defines. Detailed information on the 
DEF table may be found later in this chapter. 

DEF table of 'MODULETWO': 

MODULETWO Gbase 

M0DULETW0_M0DULETW0 Rbase+102 

MODULETWO.TWOLINES Rbase+2 

M0DULETW0__BASE Rbase 
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The Unassemble Commands 

There are two conventions used when unassembling object files: Compiler and Assembler. The 
reason for this is that the Compiler and Assembler use different conventions for the object code that 
they generate. 

The Compiler generates code so that each procedure begins with aTRAP » 1 or a L I NK «ri > AG 
and ends with aJMPorRTS. The Librarian uses this information to assume that everything from 
the beginning of the file to the first TR A P * 1 or L I NK is a constant. From the end of the procedure 
to the next TRAP * 1 or LINK is also unassembled as constants. Everything else is unassembled as 
instructions. The Assembler convention assumes that everything is an instruction. 



Note 

All Unassemble commands require a printer unless a destination file is 
specified with the P command. 

The Unassemble All (Compiler convention) Command 

Pressing ( C ) directs the Librarian to unassemble the specified object module using the Compiler 
convention described above. You can use this command on files that were created by either the 
Assembler or Compiler. Here are the results of using this command with the MOD_2.CODE 
compiled object file. 

Librarian [Ren. 3.0 15-Apr-84] 23-Apr-84 9:58:42 paSe 1 

MODULE M0DULETW0 Created 23-Apr-84 
NOTICE: (none) 

Produced by Pascal Compiler of 23-Apr-84 

Revision number 3 

Directory size 174 bytes 

Module size 3072 bytes 

Module NOT executable 

Codebase Size 104 bytes 

Global base Size bytes 

EXT blocK 5 Size 72 bytes 

DEF blocK 3 Size 90 bytes 

EXPORT block 1 Size 74 bytes 

There are 1 TEXT records 
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TEXT RECORD « 

TEXT start blocK 2 

REF start block 4 

LOAD address Rbase 



1 of 



'HODULETWO' 

Size 

Size 



104 bytes 
24 bytes 



0000 



dc • w 



ordc.bOiO ordc.b ' 

- - - - - MODULETWO_.TWOL.INES 



2 


4E41 


0000 


6 


2F2D 


FFA6 


10 


2F17 




12 


4B7A 


0030 


16 


3F3C 


0027 


20 


3F3C 


FFFF 


24 


4EB9 

0000 


0000 


30 


4AAD 


FFEA 


34 


G702 




36 


4E43 




38 


4EB9 
0000 


0000 


44 


4AAD 


FFEA 


48 


8702 




50 


4E43 




52 


4EB9 
0000 


0000 


58 


4E5E 




GO 


4E75 




52 


4920 




134 


6361 




66 


6DB5 




68 


2066 




70 


72GF 




72 


6D20 




74 


4D6F 




76 


6475 




78 


GCG5 




80 


5477 




82 


6F20 




84 


61GE 




86 


G420 




88 


6272 




90 


GF75 




92 


67G8 




94 


7420 




96 


7468 




9B 


G973 




100 


3A00 




102 


4E75 





trap *1 i«0 

moue.l SYSGL0BAL5-90(a5) ,- 

mowe.l (sp) i-(sp) 

pea Rbase+62 

moue . w «39 t- ( sp) 

mo we i w «- 1 t- ( sp) 

Jsr FS-FWRITEPAOC 

tst.l SYSGLDBALS-22(a5) 

bei.s Rbase+38 

trap *3 

Jsr FS_FWRITELN 

tst.l SYSGL0BALS-22U5) 

beq.s Rbase+52 

trap *3 

jsr MODULETHREE-THIRDLINE 



(sp) 



un 


IK 


a6 


















rts 




















dc 


ui 


18720 


o r 


dc 


b 


73 .32 


o r 


dc 


b 


'I ' 


d c 


w 


25441 


o r 


dc 


b 


88 .97 


o r 


dc 


b 


'ca ' 


dc 


ui 


28005 


o r 


dc 


b 


109 .101 


o r 


dc 


b 


'me ' 


d c 


w 


B294 


o r 


dc 


b 


32.102 


o r 


dc 


b 


' f ' 


dc 


w 


29295 


o r 


dc 


b 


114.111 


o r 


dc 


b 


' ro ' 


dc 


w 


2793G 


o r 


dc 


b 


109.32 


o r 


dc 


b 


'm ' 


dc 


Ul 


19823 


o r 


dc 


b 


77 .111 


o r 


dc 


b 


'Mo ' 


dc 


ui 


25717 


o r 


dc 


b 


100 .117 


o r 


dc 


b 


'du' 


dc 


w 


27749 


o r 


d c 


b 


108 ,101 


o r 


dc 


b 


'le ' 


dc 


w 


21823 


o r 


d c 


b 


84 ,119 


o r 


dc 


b 


'Tui ' 


dc 


u 


28448 


o r 


dc 


b 


111 .32 


o r 


dc 


b 


' o ' 


dc 


Ul 


24842 


o r 


dc 


b 


97.110 


o r 


dc 


b 


' an ' 


dc 


Ul 


25632 


o r 


dc 


b 


100 .32 


o r 


dc 


b 


'd ' 


dc 


Ul 


25202 


o r 


dc 


b 


98.114 


o r 


dc 


b 


'br' 


dc 


Ul 


28533 


o r 


dc 


b 


111,117 


o r 


dc 


b 


' ou ' 


dc 


Ul 


2G472 


o r 


d c 


b 


103,104 


o r 


dc 


b 


'Sh ' 


dc 


Ul 


29728 


o r 


dc 


b 


116,32 


o r 


dc 


b 


't ' 


dc 


Ul 


29800 


o r 


dc 


b 


116,104 


o r 


dc 


b 


'th ' 


dc 


Ul 


26995 


o r 


d c 


b 


105,115 


o r 


dc 


b 


'is' 


dc 


Ul 


14848 


o r 


dc 


b 


58 ,0 


o r 


dc 


b 


' : ' 


dc 


Ul 


20085 


o r 


d c 


b 


78 ,117 


o r 


dc 


b 


'Nu' 
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The Una ssemb le All (Assembler Convention) Command 

Pressing ( A ) will cause your computer to unassemble the specified object module using the 
Assembler convention described above. You can use this command on files that were created by 
either the Assembler or Compiler. 



Note 

Use of the Assembler convention may produce unpredictable results, 
because under this convention there is no way to tell code from data. 
Files produced by the Compiler and unassembled under the Compiler 
convention will almost always produce reasonable results. 

Here is the unassembly of the MOD_2.CODE object file using the Assembler convention. Notice 
that, with Assembler convention, the first two bytes ($0000) are assumed to be code; with Compiler 
convention they are assumed to be data (remember that the Compiler convention assumes that 
anything until the first TRAP #1 or LINK »n >AS is assumed to be data). Notice also that the 
module heading shows that this object module was produced by the Compiler. 

Librarian tRev. 3.0 15-Apr-84] 23-Apr-B4 10: 1:34 paSe 1 

MODULE M0DULETW0 Created 23-Apr-84 
NOTICE: (none) 

Produced by Pascal Compiler of 23-Apr-B4 

Revision number 3 

Directory size 174 bytes 

Module size 3072 bytes 

Module NOT executable 

Code base Si2e 104 bytes 

Global base Size Obytes 

EXT blocK 5 Size 72 bytes 

DEF blocK 3 Size 90 bytes 

EXPORT blocK 1 Size 74 bytes 

There are 1 TEXT records 

TEXT RECORD « 1 of 'M0DULETW0': 

TEXT start blocK 2 Size 104 bytes 

REF start blocK 4 Size 24 bytes 

LOAD address Rbase 

0000 4E41 ori.b *G5,dO 

4 0000 2F2D ori.b *45,d0 

8 FFA6 dew -90 or dc.b 255»1BG or dc.b ' 

10 2F17 move. 1 (sp)i-(sp) 

12 4B7A 0030 pea Rbase+62 

IB 3F3C 0027 moue.w *39.-<sp> 

20 3F3C FFFF mowe.u »-1.-(sp) 

24 4EB9 0000 Jsr FS-FWRITEPAOC 
0000 
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30 


4AAD 


FF : EA 


tst.l SYSGL0BALS-22(a5> 


34 


6702 




beq.s Rbase+38 


3G 


4E43 




trap *3 


38 


4EB9 
0000 


0000 


Jsr FS-FWRITELN 


44 


4AAD 


FFEA 


tst.l 5YSGL0BALB-22(a5) 


48 


6702 




beq.s Rbase+52 


50 


4E43 




trap *3 


5;: 


4EB9 
0000 


0000 


jsr MODULETHREE-THIRDLINE 


513 


4E5E 




unlk a6 


60 


4E75 




rts 


62 


4920 




lea -( aO) ta4 


64 


6361 




bls.s Rbase+163 


613 


BD65 




blt.s Rbase+169 


68 


2066 




movea . 1 - ( a6 ) >aO 


70 


726F 




mouei #111 id 1 


72 


6D20 




blt.s Rbase+106 


74 


4D6F 


6475 


lea 25717(sp) ,a6 


713 


6C65 




b*e .s Rbase+181 


80 


5477 


6F20 


addq . w *2 »32(sp td6. 1 ) 


84 


616E 




bsr.s Rbase+196 


8(3 


6420 




bco.s Rbase+120 


813 


6272 




bhi.s Rbase+204 


90 


6F75 




ble.s Rbase+209 


92 


6768 




beq.s Rbase+198 


94 


7420 




KDuei *32td2 


9(3 


7468 




mouei #104(d2 


98 


6973 




bus.s Rbase+215 


00 


3A00 




move . w dO »d5 


02 


4E75 




rts 



The Line Rang e (Compiler Convention) Command 

Pressing ( L ) causes two prompts to be displayed. The computer needs to know the line number 
range to unassemble. The code will then be unassembled up to, but not including, the upper range 
value. The object module must have been compiled using the $DEBUG ON$ Compiler option to 
be unassembled with this command. 

The PC Range (Assembler Convention) Command 

Pressing ( P ) causes two prompts to be displayed. The computer needs the location counter 
values of the segment of code you want unassembled (relative to the relocation base of the 
module). The code will then be unassembled up to but not including the upper location counter 
value. 
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Creating a New Boot File 

At power-up, the Boot ROM searches mass storage for system Boot files: Boot ROMs 3.0 and later 
versions search all mass storage devices on-line and let you choose which Boot file you want; earlier 
Boot ROMs choose the first Boot file found on the right-hand internal disc drive. A Boot file is then 
loaded by the Boot ROM. The Boot file in turn may load other parts of a system. (For further details 
of how this system boots, see the discussion called The Booting Process in the Special Configura- 
tions chapter. ) 



The [ B ] command is used to create Boot files. This is an advanced option and should only be 
used if you have a clear understanding of system generation. 



The following is an overview of the system generation process using the ( B ) command. 



Note 
The B command cannot create boot files in WS1.0 directories. 



1. Use the Editor to produce the programs and modules that will make up the new boot 
program. Both Assembler language and Pascal modules may be used. 

2. Assemble the Assembler language modules and compile the Pascal modules. 

3. Use the Librarian to Link the code files together as desired. Be sure to specify the global and 
relocation bases. In addition, this file must have no unsatisfied external references. Note that 
the first program linked will provide the start address for the Linked file. This start address will 
also become the start execution address of the system Boot file at boot time. 

4. Keep the linked file. 

5. Specify the linked file as the Librarian Input file. 

6. Now press ( B ) to properly place the module name in the destination's directory and 
format the code for use by the boot ROM. The B command moves the cursor up to the 
Output file prompt. 

7. Specify the Output file as SYSTEM_xxx (the xxx can be any characters syntactically allowed 
for file names. With Boot ROMs 3.0 and later, the name can be SYSxxxxxxx; see Re- 
Naming BOOT: Files in the Special Configurations chapter for examples). Be sure to append 
a trailing period to the file name to keep a suffix from automatically being appended to the 
name. 

8. Transfer the Input file into the boot file. This copies the code file. 

9. Press ( B ) again to finish the Boot operation. 

10. You can now either Quit the Librarian or power up and test your new system. 
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Librarian Command Reference 

The Librarian command set consists of single-letter commands allowed when the letter prompts are 
displayed on the screen. You press the corresponding key to cause the command to be executed. 



( A ) In Copying and Linking modes, this command transfers All modules from the Input file to 
the Output file. 

In Edit mode, this command is used to Append modules to the Output file. 

In Unassemble mode, this command directs the Librarian to unassemble the Input file 
using Assembler conventions. 

( B ) The Boot command is used to create code files that are loadable by the Boot ROM. The 
Boot command is given instead of the Output file command. The Input modules are then 
combined in a format that is bootable. This command should only be used by system 
designers. A boot file must be a self-contained processor environment. It must be stored 
on a LIF or SRM volume and be named SYSTEM_xxx, where xxx represents any 
combination of characters. If you have Boot ROM 3.0 or later version, the file can be 
named SYSxxxxxxx or stored on an SRM system under the /SYSTEMS directory. 

( C ) In the Link mode, this command returns you to Copy mode. While in Copy mode, you 
can combine modules into a library without Linking. This mode can be used to add 
modules to (or remove them from) the System Library, your own library, or INITLIB (the 
Initialization Library file which is executed during the boot process). 

In Edit mode, this command Copies the First module up to (but not including) the Until 
module to the Output file. 

In Unassemble mode, this command unassembles the Input file according to Compiler 
conventions. 

( D ] In Link mode, this command controls whether or not the DEF table is included in the 
Output file. If the Output file is to be Linked to another file later, the DEF table must be 
left in the Output file. If the Output file is not to be Linked, you can save memory space 
by rem oving the DEF table. A YES includes the DEF table, a NO removes it. Pressing 
( D ) toggles between these two choices. 

In Unassemble mode, this command prints the DEF table. 

( E ) This command is available when you have specified both Input and Output files. It puts 
you into Edit mode, which allows you to combine modules in the Input file with Append 
modules and place them into the Output file (while either Copying or Linking). 

In Unassemble mode, this command prints the Ext table. 

( F ) This command prints the File directory of the Input file on the current Printout file 
(external printer or file). It doesn't matter whether the Printout prompt is ON or OFF; 
the printout will be sent to the Printout file. 

In Edit mode, this command is used to specify the First module to be transferred to the 
Output file. (The First module must precede the Until module in the Input file. ) 

( G ) In Linking mode, designate the Global base address (most useful when preparing a file 
for use as a system Boot file). 
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( H ) The Header command allows you to change the size of the library header. From 1 
through 18 module entries require only one header block, so a header size of 18 is the 
minimum. If you specify less (but not 0), you will still be given 18. From 19 through 38 
module entries requires two header blocks. This is the default header size. The specifica- 
tion is made in units of module entries - not blocks. The Librarian calculates how many 
blocks are necessary to maintain the number of modules you specify and then gives you 
the maximum number of entries that will fit in that number of blocks. 

( I ) Name the Input file containing the modules you want to transfer to the Output file. 
".CODE" is automatically appended to the file name unless suppressed by a trailing 
period (or by the presence of another standard suffix). This prompt can be used many 
times to collect modules from several object files into your new object file. 

( K ) Keep the Output file. Close and lock it into the directory, purging any old file of the same 
name. 



( L ) Enter Linking mode or finish Linking. 

In Unassemble mode, you can use this command to unassemble a section of code 
defined by two Line values using the Compiler convention. The code must have been 
compiled using the $DEBUG ON$ Compiler option. 

( M ] Enter the specific Module name you want to transfer. (The first module in the Input file is 
automatically displayed when an Input file is specified. ) 

( N ) In Linking mode, name the New object module to be created by the Librarian. If you do 
not specify specify a new module name, the name of the first module transferred will be 
used. 

( ) Name your Output file. ".CODE" is appended automatically unless suppressed by a 
trailing period (or standard suffix) in the file name. This Output file must remain on-line 
throughout the process of transferring modules to it. 

( P ) This command is used to turn the Pri ntou t optio n O N or O FF (the default is OFF) and to 
select a Printout file. Pressing ( P ) and ( Return ) or (ENTER) turns the option ON. With the 
option ON, the device to which the information is sent is shown on the screen. The 
default Printout file specification is "PRINTER:LINK.ASC" unless you specify another. 
".TEXT" is automatically appended to the file name unless it is suppressed by a trailing 
period (or standard suffix) in the file name. 

Before any information is sent to the Printout file, the Librarian first sends heading 
information to the device. When Linking, you will get a map of all Linking done by the 
Librarian. This option does not affect any information sent to the Printout file by the 
Unassemble commands. 

In Unassemble mode, this command allows you to unassemble (using Assembler con- 
ventions) a section of code defined by two location counter range values. 
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( Q ) Quit the Librarian and return to the Main Command Level. 

( R ) In Linking mode, designate the Relocation base address to be used. 

( S ) In Linking mode, this command assigns Space for patches. To save execution time and 
memory space, the Compiler can be made to use PC-Relative addressing instead of 
Long-Absolute addressing. This is done with the Compiler option $CALLABS OFF$. 
The PC-Relative addressing mode has an address range of - 32 768 through 32 767 
bytes; if the referenced procedure is out of this range, an error will occur at load or link 
time. This error prints an error message naming the module having the link out of range. 
To fix this, relink the modules adding patch space between them as needed. The number 
of bytes needed depends on the particular module. As a rule of thumb, begin with a 
patch of 100 bytes. 

In Edit or Unassemble modes, this command Stops the Edit or Unassemble session and 
returns to the Librarian's main prompt. (This will not stop an ongoing Unassemble; 
however, the ( Stop ) key will. ) 

( T ) In Copying and Linking modes, this command Transfers the object module currently 
named in the Transfer prompt to the Output file. 

In Unassemble mode, this command prints the interface Text (DEFINE SOURCE) of the 
current Input module. 

[ U ) Enter the Unassemble mode. 

In Edit mode, this comman d allow s you to spec ify the Until module. If you enter a null 
response (by pressing (Return) or (ENTER) with no file specification), then 
(end of f i 1 e ) is displayed; a subsequent Copy will copy all remaining modules in 
the Input file (i.e., up to the end of the file) to the Output file. 

( V ) This command gets you into the Verify mode. This mode displays the na me of e ach 
module in the Input file and allows you to Transfer it to the Output file (press ( T ) ), to 
Unassemble it, or to not transfer or unassemble it (press the space bar) and step to the 
next module name. After all module names have b een di splayed, you automatically 
leave this mode. To re-verify the file's contents, press ( V ) again. 

[ X ) In Linking mode, this command allows you to enter a copyright notice as part of the 
Output file. The notice is part of the heading information sent to the Printout file. The 
notice can be up to 255 characters long. 
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Glossary of Object Code Terminology 

Here are detailed definitions of the terms used in this manual regarding object-code library files. 

DEF table (Definition Symbol Table) 

There is only one DEF table per module. It contains one DEF record for each symbol which is 
exported from the module. The DEF table begins on a block boundary which is specified in the 
directory for the module. Its length is also given in the directory. The DEF table is contiguous over 
its length, which means that individual DEF records within the table may cross block boundaries. 

Each DEF record has two parts. The first part is a packed string containing the name of the symbol 
which is defined. The string begins and ends on a word (even-byte) boundary. If the string length is 
odd, then an extra byte is added to the end for padding so that the next part of the DEF record will 
begin on a word boundary. 

The second part of a DEF record is a general value or address record (GVR) which defines the 
value of the symbol which is being exported. GVR is defined later in this section. 

The value extension is 4 bytes or 8 bytes long, according to the data size field. The value of the 
symbol is defined to be the value extension plus what ever references are specified by the primary 
type and any Reference Pointers that may exist. The value extension must be present. 

DEF record 



low 



high 



LEN = 6 


S 


Y 


M 


B 





L 


padding 


flags 


len = 8 


value (high part) 


value (low part) 


ref pointers (....) 



First part 



Second part 

(len is Second part length) 

(GVR includes any number of reference pointers) 



DEFINE SOURCE 

This is the section of an object module that is searched by the Compiler when the module is 
imported (also called "interface text"). With Pascal modules, the DEFINE SOURCE consists of the 
declarations made by the reserved words MODULE, IMPORT (if present), and EXPORT. With 
Assembler modules, it consists of the lines defined by the SRC pseudo op, which are intended to 
serve the same function as in Pascal modules (however, it may be any arbitrary text). 

There may be one table of DEFINE SOURCE per module. It begins on a block boundary, which is 
given in the module directory. The length is also given in the directory. 
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EXT Table (External Symbol Table) 

The EXT table contains records (Pascal strings), each of which is the name of a symbol referenced 
in this module, but not defined in it (i.e., these symbols are declared in another module which this 
one imports and to which this module is linked at load time). 

There may be one EXT table per module. The EXT table begins on a block boundary which is 
specified in the directory for the module. Its length is also given in the directory. The EXT table is 
contiguous over its length, which means that individual EXT records within the table may cross 
block boundaries. 

Each EXT record is a multiple of four bytes long. The first byte of each string is its length (according 
to the Pascal string type); thus strings may be from 1 to 255 bytes long. If strlen(string) + 1 is not a 
multiple of 4, then 1 to 3 bytes are added as padding to make the EXT record extend to the proper 
boundary. 

The first eight bytes of the EXT table are reserved. Thus, the first string in the table starts at an offset 
of 8 from the start of the table. 

The EXT table is restricted to 65 532 bytes in length (plus the length of the last string). This is so that 
any entry in the table can be uniquely referenced by 14 bits; the reference is relative to the start of 
the table. See the description of the reference pointer. 



low 



high 



left byte 



LEN = 6 


S 


Y 


M 


B 





L 


padding 



EXT Record 

right byte Thjs one jg 8 bytes | ong 

The formula is: 

EXTsize = len + 4 - (len mod 4) 



298 The Librarian 



EXPORT 

EXPORT is a reserved word used in the Pascal Module. It is used to declare those procedures, 
functions, constants, types, and variables that are exported, or made available, to other modules 
that import the module. 

Flags 

Flags are used in the DEF table, in REF tables, and in the GVR. Their form is shown below. 
Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 



Primary Type 


Data Size 


Patchable 


Value-Extend 


Long Offset 



primary type: 



data size: 



patchable: 
value extend: 

long offset: 



00 absolute 

01 relocatable 

10 global 

11 general 

000 signed byte (8 bits) 

001 signed word (16 bits) 

010 signed long (32 bits) 

011 (reserved) 

100 unsigned byte (8 bits) 

101 unsigned word (16 bits) 

110 (reserved) 

111 (reserved) 



:no REFERENCE POINTERS follow 
:no REFERENCE POINTERS follow 
:no REFERENCE POINTERS follow 
:one or more POINTERS follow 

-128.. 127 

-32768..32767 

- 2 147483648. . 2 1 47483647 

0..255 
0.. 65535 



Indicates that the linker may patch a location in a TEXT record. Applicable only 
in a REF record and must be false everywhere else. 

No extension present, assume 

1 Value extension present. Length is 4 bytes. 
Always true in DEF records. 

Use short form (1 byte) of offset field. Value is in the range 0..255 and specifies 
the total length of the GVR except in REF records. 

1 Use long form (3 bytes) and offset field. Value is a 24 bit unsigned number 
in the range 0.. 16777215. Applicable only in some REF records. 



Note 
Data Size should be signed long everywhere except in a REF record. 
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General Value or Address Record (GVR) 

The GVR is a variable length record which is intended to represent any absolute, relocatable, or 
linkable value. 

TYPE DATATYPE = (sbyte. sword, sinti fltpti uby t e . uwa rd ) ! 

RELOCTYPE = (absolute) relocatable. global, general)! 
GENERALUALUE = PACKED RECORD 

PRIMARYTYPE : RELOCTYPE! (*allows quicK indication 

of most common types*) 
DATASIZE : DATATYPE! (*specifies 1.2 or 4 bvtesi signed or not*) 

PATCHABLE > (*specifies self relative field in branch*) 

VALUEEXTENDED : BOOLEAN! Vindicates v al ueex t en i on* ) 
CASE LONGOFFSET : BOOLEAN OF <*1 or 3 byte offset*) 
FALSE : ( sh o rt : . . 255 ) i (*unsigned B bits*) 
TRUE : long:0. . 1G777215) i (♦unsigned 24 bit value*) 
END! 

VALUEEXTENTION = PACKED (*present if value extended bit above is set*) 
RECORD 
CASE DATATYPE OF 

SBYTE, SWORD. SINT, 

UBYTE.UWORD : (value integer)! 
END! 
REFERENCEPTR = PACKED RECORD (*one or more present if type = general*) 

ADDRESS : 0. .16383! (*multiply by 4 to get address of EXT symbol*) 

OP : ( ADDIT .SUBIT) i (*add or subtract the modifying value*) 

LAST : BOOLEAN! Vindicated end of list*) 

END! 

GVR = CONCATENATION (*N0TE* This is pseudo pascal*) 

GENERALVALUE! (#2 to 4 bytes of header info*) 

YALUEEXTENTION! <*0 or 4 bytes of value*) 

ARRAYCzero or more] OF 

REFERENCEPTR! (*list of EXT references*) 

END! 

IMPLEMENT 

IMPLEMENT is a reserved word used in the Pascal Module. It is used as a flag to indicate the 
beginning of the module body. It is made up of the reserved word plus a declaration statement. The 
statement can be either empty or used to declare those constants, variables, procedures and 
functions used internally by the module. None of this information is available outside the module 
(unless it is also declared in the module's EXPORT section). 

IMPORT 

IMPORT is a reserved word used in the Pascal Module. It names the modules whose DEFINE 
SOURCE sections must be examined by the Compiler in order to resolve references to constants, 
variables, procedures, and functions exported by the modules. The Compiler uses a module's 
name in conjunction with names of constants, procedures, and functions declared in the module to 
generate EXT strings for which the loader will search (and link) at run time. 

LIBRARIAN 

The Librarian is a subsystem designed to manage HP Series 200 Pascal and Assembler object files, 
link and unassemble object modules, and create system Boot files. It can merge object files contain- 
ing object modules and optionally link the object modules together. It is the file named LIBRARIAN 
in your operating system, which can be changed with the Main Level's What command. It is 
accessed by pressing ( L ] from the Main Command Level. 
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Library 

A library is an object file produced by the Assembler, Compiler, or Librarian. Its purpose is to 
contain object module(s). 

LIBRARY 

LIBRARY is a special library file included with your operating system. During the boot process, this 
file (if on-line) generally becomes the System Library; you can also use the What command at the 
Main Level to specify any file as the System Library. 

Only a few useful object modules are included in the file when you received it. Feel free to examine 
them with the Librarian. Other object modules are supplied on the LIB: and FLTLIB: discs and may 
be added to the LIBRARY. 

Object File 

An Object File is the unit of object code managed by the Librarian. It is made up of a Library 
directory and one or more object modules. The Assembler generates one object file from each 
source file assembled; the Compiler also generates one object file per invocation. The Compiler's 
object file can contain one or more object modules depending upon the source file's construction. If 
the source file contains a number of compilable modules, that number of object modules will be 
created in the object file. 

Object Module 

Each object module is made up of a module directory and a module body. The module body is 
made up of the following items: 

One EXT table A table of the symbols imported by the module. 

One DEF table A table of symbols exported by the module. 

One DEFINE SOURCE A software interface between the module and any program which 
Area imports it. 

One or more A TEXT record consists of the constants and code instructions that 

TEXT-Record/REF-Table make up the program. The REF table is a directory of the symbols 
pairs used in the TEXT record. 

Pascal Module 

HP Pascal allows source modules to be compiled separately into object modules. The object 
modules are generally not executable, but are used to complete other Pascal programs. Examples 
are given earlier in this chapter. 
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REF Tables 

Each REF table follows a TEXT record and is associated with that TEXT record. The REF table 
begins on a block boundary, which is specified in the directory for the module. Its length is also 
given in the directory. The REF table is contiguous over its length. 

Each REF record is associated with one object (byte, word or integer) within the preceeding TEXT 
record. There can be at most one REF record for a given object in the TEXT record. The REF 
records are ordered within the table according to the TEXT objects they reference. 

The offset field specifies which text object is referenced. The first REF record gives an offset from 
the beginning of the TEXT record. Subsequent REF records give an offset from the object refer- 
enced by the previous REF record. 



low 



high 



flags 



offset 



offset (low part) 



Ref pointers 



Ref record is a GVR. 

offset, 1 or 3 bytes, indicates next object in TEXT record. 
Can include any number of Ref Pointers. 



Reference Pointer 



Bit 15 thru Bit 2 


Bit 1 


Bit 


Address of an EXT Record 
Relative to Beginning of EXT Table 


Add or Sub 


End Flag 



A REFERENCE POINTER is the relative address of an entry in the EXT table. 

The add or sub flag indicates whether the value of the external symbol is to be added (0) or 
subtracted (1) from the GVR value in order to obtain the actual value. There may be any number of 
REFERENCE POINTERS in a GVR, and there may be more that one reference to the same EXT 
record. There may not, however, be both an add reference and a subtract reference to the same 
symbol, since these would cancel each other. 

The end flag indicates whether there are any more REFERENCE POINTERS in the GVR. (0) 
indicates more to come, (1) indicates the end. 

There are two special cases for the EXT address. 

• Address (bit pattern OOOOOOOOOOOOOOxx) refers to the relocation delta for the current 
module (i.e. new load address minus the old load address). 

• Address 4 (bit pattern 0000000000000 lxx) refers to the global delta for the current module 
(i.e. new data address minus old data address) 

Address 8 (bit pattern 00000000000010XX is the first valid reference to an external symbol. 

There are REFERENCE POINTERS in a GVR only if the primary type field specifies general. 
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System Library 

The System Library is a file that is automatically accessed by the Compiler at compile time and by 
the linking loader at execution time. Object modules stored in this object file are automatically 
available to any program importing them. 

During the booting process, the LIBRARY file usually gets designated as the System Library; 
however, you can use the What command at the Main Level to specify any file. See LIBRARY 
above. 

Text Record 

A Text record is a contiguous section of code, beginning on a block boundary, which is given in the 
module directory. The length is also given in the directory. The text record can be any arbitrary 
data, but is usually the object code produced by the Compiler or Assembler. 
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The Debugger 



Chapter 



Introduction 

The Workstation Pascal System features a programming aid called the Debugger. As you probably 
have guessed, the major purpose of the Debugger is to make program debugging as painless as 
possible. 

You may have already seen a reference to this Debugger when you got this message: 

RESTART WITH DEBUGGER? 

The question is in response to a user program generating but not trapping an "exception. " You will 
learn how to answer the question in this chapter. 

Here are some of the operations you can perform with the Debugger: 

• Step through programs on a procedure, statement, or machine-instruction basis. 

• Maintain a record of the statements which have already been executed (in order of execution). 

• Examine any memory locations and CPU registers, and display the contents in any of the 
following formats: binary, octal, decimal, or hexadecimal integer; real number; alphanumeric 
character; and Assembler instruction. 

• Set up "breakpoints" and "error traps" in the program, optionally displaying helpful informa- 
tion when each is encountered. 

• Perform number-base conversions and integer arithmetic calculations. 

The main emphasis of this chapter is to describe using the Debugger to debug Pascal programs. 
Debugging an Assembler-language program is more direct; that information is obtainable from the 
Debugger Reference Section. 

Is the Debugger Loaded? 

The Debugger is a very powerful subsystem, because it allows any user to access everything in the 
computer. It is therefore a potentially dangerous feature in the hands of users who don't know how 
to use it (or who you don't wanrto use it). For this reason, and for space considerations, it is nor 
automatically loaded when you boot the system. Therefore, you will need to load the Debugger 
before attempting to use it. (In previous system versions, it was automatically loaded at boot time, 
as it was part of the INITLIB file). Loading the Debugger is explained in the following Sample 
Session section. 
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A Sample Session 

This section describes methods for debugging Pascal programs with the aid of the sample program 
called DEBUG, supplied to you on the DOC (documentation) disc. The program is given in source- 
code and object-code form. 

• DOC : DEBUG . TEXT - the source-code file 

• DOC : DEBUG . CODE - the object-code file 

The Example Program 

A listing of the program is included here for reference. Note that a Pascal program must contain the 
$ DEBUG 0N$ Compiler option if you want to have the ability to halt the program at particular line 
numbers. The effects of this option are further described in the Compiler chapter. 



Pascal 


[Rev 3 


.0 


4/15/84] 


DEBUG 


TEXT 28-Apr-84 14:21 


1 :D 







*DEBUG 0N$ 


< Ena 


jle debuSSinS. } 


2:S 












3:D 







PROGRAM XYZ 


(OUTPUT) i 


4:D 






VAR 






5:D 


-a 




i 




INTEGER! 


6:D 


-B 




j 




integer; 


7:D 


-IB 




X 




real; 


8:D 


-24 




y 




real; 


9:D 


-25 




chl 




char; 


10 :D 


-2G 




oh2 




char; 


11 :S 












12:D 




1 


PROCEDURE Lbuj 


■ i_i ; 


13:D 




2 


1.' A R 






14:D 


-a 


2 


i 




integer; 


15:D 


-8 


2 


X 




integer; 


1G:D 


-12 


2 


y 




integer; 


17:B 












18:D 




2 


PROCEDURE L 


-evel_2b i 


19:C 




3 


BEGIN 




20*C 




3 




WRITE 


:< 'Leuel 2b: ' ) ! 


21*C 




3 




WRITE 


K' i = ' i i : 2 i ' x= ' tx : 4 ) ! 


22*C 




3 




WRITE 


:LN( ' chl= ' .chl : 1 ) ; 


23*C 




3 


end; 




24:S 












25:D 




2 


PROCEDURE L 


. e M e 1 _ 2 a i 


2B:D 




3 


VAR 




27:D 


-12 


3 




i t x 


y : INTEGER! 


28;S 












29:D 




3 


PROCEDUr 


!E Leuel_3i 


30:C 




a 




BEGIh 


J 


31*C 




4 




IF 


" i < 4 THEN 


32:C 




5 






BEGIN 


33*C 




5 






WRITE! 'Level 3: ') i 


34*C 




5 






WRITE! ' i= ' ii :2 , ' x= ' ix:4) i 


35*C 




5 






WRITELN! ' ohl= ' tohl : 1 ) » 


3G»C 




5 






i : = i + 1 i 


37*C 




5 






L e i.i e 1 _ 3 ! 


38:C 




5 






end; 


39*C 




a 




IF 


chl='a' THEN 


40:C 




5 






BEGIN 


4i*c 




5 






ch 1 : = ' x ' i 


42»C 




5 






WRITE! 'Level 3: ' ) i 


43*C 




5 






WRITE! ' i= ' ,i :2 . ' x= ' ,x:4) i 


44*C 




5 






WRITELN!' chl= ' .chl:l ) i 


45:C 




5 






end; 


4B*C 




a 




end; 




47:S 
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48 :C 
49*C 
50*C 
51*C 
52*C 
53*C 
54*C 
55#C 
56*C 
57:S 
58:C 
59*C 
60*C 
S1*C 
B2*C 
B3*D 
64*C 
G5*C 
6G:S 
G7:C 
G8*C 
G8*C 
70*C 
71#C 
72*C 
73*C 
74*C 
75*C 
76*C 
77*C 
7B*C 
79:S 



BEGIN 

WRITEf 'Level 2a: 



kRITE( ' 
WRITELNf ' 
i : = 1 ! x : 
Leuel_3 i 
i := 4i x: 
L e i.i e 1 _ 2 b i 



i=' ii:2 

chl= ' 

= 2! v: 

= 5 i y : 



' ) i 
' x = ' »x 
chl : 1 ) 5 

3! 

s; 



:4> 



end; 

BEGIN 

i : = ! x : = i : 
WRITEf'Leuel 1: 
WRITE( ' i= ' .i : 
WRITELN(' chl= 
Leuel_2b i 
Leuel_2a i 

END! 



:= Oi 

' ) ; 

2.' x=' 
' .chl :1 ) 



.x:4) 



BEGIN 

i:= 10! 

x : = 20.0 i y : = 30. Oi 
chl : = 'a' i ch2:= 'b ' i 
WRITE! 'Main: ' ) i 
WRITEf ' i= ' .i :2 , ' x= ' .x:2: 1 ) 
WRITELNf' chl= ' .Bhlrl ) i 
L e u e 1 _ 1 i 

WRITE('Hain: ')! 
WRITE! ' i= ' .i :2 . ' x= ' .x:2: 1) 
WRITELNf ' ohl= ' .chl : 1 ) i 
END. 



No errors. No w a minis. 

Please Participate 

You will learn much more about the Debugger if you participate in this sample session. Execute the 
code file one time before attempting the sample session to see the program's output. 

Loading the Debugger 

As previously mentioned, the Debugger is not automatically loaded as part of the standard system, 
so you will need to load it into the computer. You can load the module in either of two ways: 

• Execute it using the eXecute command (from the Main Command Level); the program installs 
itself. 

• Add the DEBUGGER module to INITLIB, and re-boot the system; the program is then 
installed automatically. 

Loading the Debugger with the eXecute command allows you to use it until you re-boot the system, 
at which time you will have to eXecute it again to use it. By adding the module to INITLIB, you give 
all users (who subsequently boot with this INITLIB file) access to the Debugger. You will not want 
to use this second method unless you want to give all users access to the Debugger. 
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Executing the Debugger 

First, make sure that the ASM: disc is on- line or that the file is otherwise accessible. Then, from the 
Main Command Level, press the [ X ) key to initiate the eXecute command. The system will 
prompt you with this message: 

Execute what file? 

Respond by entering the specification of the DEBUGGER file; ASM:DEBUGGER. will work if you 
are loading the program from the original disc (remember to type a trailing period to suppress the 
.CODE suffix). The system then loads and executes the program, which installs itself in memory. 

Adding the Debugger to INITLIB 

Use the Librarian (from the Main Command Level) to add this module to the INITLIB file. In 
general, the steps can be summarized as follows: 



1. 
2. 



3. 

4. 
5. 



Make a back-up copy of INITLIB. 

Edit the INITLIB file with the Librarian, adding the DEBUGGER module (supplied on the 
ASM: disc) to the file. The DEBUGGER can be anywhere after the modules named KEYS, 
BAT, and CLOCK; however, it must be before the module named LAST. (Editing libraries is 
described in the Librarian chapter.) 

Store the new library file (using the Keep command). 

Remove the INITLIB file on your BOOT: disc, and add your new INITLIB file. 

Re-boot the system. 



After re-booting the system, the Debugger should be in memory. 

A Note about Key Notations 

Throughout this chapter, you will be shown which keys invoke certain Debugger functions. Since 
you may have one of three different keyboards connected to your computer, each with a different 
set of keys, you will need to learn which key to press on your keyboard. Here are examples of keys 
used to invoke a few functions on the three different keyboards 1 . 



Desired 


HP 46020A 


HP 98203B 


HP 98203A 


Function 


Key(s) 


Key(s) 


Key(s) 


Pause 


( Break ) 


f PAUSE) 


( PSE) 


Single Step 


((System)) ( fi ) 


( STEP ) 


( STEP ) 


Slow Step 


((System))( CTRL) -( /5 ) 


( CTRL)-( STEP) 


( CTRL)-( STEP) 


Continue 


((System)) ( M ) 


( CONTINUE ) 


( CONT ) 



For instance, invoke the Pa use fun ction on a 46020 keyboard by pressing t he ( Break ] key. On a 
98203B keyboard, press the (PAUSE) key. With a 98203A keyboard, press the ( PSE ) key. 



1 This discussion only gives a few examples; the Debugger Keyboard section near the end of the chapter describes all key(s). 
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As another example, suppose that you want to invoke the Single-Step function. On both 98203A 
and B keyboards, press th e ( STEP ) key; the label is on the key itself. On a 46020 keyboard it will be 
the System key labeled [ f5 ) on the key, which is labeled STEP on the screen while in the 
System -key mode. (If you are no t already in System-key mode, then you will need to press the 
[System) key before pressing [ /5 ) ). The sa me nota tion is u sed for the other System keys on the 
46020 keyboard; the actual System key (i.e., [ f\ ) through ( f% ) ) is not given in text; the label is 
instead given. You will need to make the association, which yo u can easily do by looking at the 
System-key labels while the Menu is bei ng disp laye d (pres s the ( Menu ) key to toggle the Menu on 
and off). If you are not familiar with the [System] and ( Menu ) keys, read the discussion in the Pascal 
User's Guide. 

The convention used in this manual is to show the 46 20 key s first (followed by the equivalent 
98203B key in parenth eses). For instance, the ( Break ) ( [PAUSE] ) key in vokes the Pause function: 
on the 46020, it is the Qreak] key; on a 98203B keyboar d, it is the ( PAUSE) key. (The 98203A 
( PSE ) key is not shown, because it is close enough to the ( PAUSE) label that you should be able 
to easily make the connection. ) 

Is the Debugger Installed? 

Before proceedi ng, yo u shou ld verify that the Debugger is currently installed. On a 46020 
keyboard, press ( Break ) ( (PAUSE) ) to pause the system. If a p is displayed in the lower, right-hand 
corner of the screen, then the Debugger is installed. Press C0NT ( ( CONTINUE ) ) to resume operation. 

If the Debugger is not installed, then pressing [ Break ) will do nothing. 

Invoking the Debugger 

The Debugger is called from the Main Command Level. When the Debugger is invoked, the system 
will then take steps to determine which program you want to debug. Before invoking the Debugger, 
let's look at how it determines which program to debug. 

Specifying a Program 

When the Debugger is invoked, the system will either look for a code file on its own or ask you for 
the code file's name, according to the following priorities. (If the Debugger is not installed, then the 
D command is identical to the eXecute command.) 

1. If there is currently an object-code workfile, the file is automatically loaded into computer 
memory. If there is a source-code workfile (but not an object-code file), the system reports 
that it cannot open the file because it was not found. 

2. If there is no workfile, the second check made is for the last file compiled since power-up. If 
present, that file is then loaded. 

3. If neither such file exists, you are prompted for a file name. 

If you plan to debug, edit, and recompile a program several times in a session, using a workfile may 
be the best alternative; you will not have to keep typing in the file name, because the current 
workfile is the automatic object of those subsystems. 
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For this session, we will set up a workfile. First, use the Filer's What command to see if there is 
already a workfile. If it happens to be the DEBUG. CODE file, you need do nothing more (before 
exiting the Filer). Otherwise, use the Get command to specify the example program as the workfile. 
Here is the prompt you will see: 

Get what file? 

Answer by entering the file specification of the example program. Type: 



DEBUG (Return) or (ENTER) 
The filer responds with something like this: 
Source and code file loaded » 



You may now Quit the Filer. Now press the ( D ) key while at the Main Command Level to 
invoke the Debugger. 

Answering RESTART WITH DEBUGGER? 

As mentioned earlier, this prompt is shown any time that a "user" program generates but does not 
trap an exception. Answering "Yes" to this question will also get you into the Debugger; you will 
effectively be at the same point as if you had used the D command. (If the Debugger is not currently 
installed or if the program was not compiled with the $DEBUG ON$ option, answering "Yes" will 
only re-execute the program.) 

The Debugger Command Screen 

You are now in the Debugger's command screen. This message indicates that the Debugger is 
ready for further instructions: 

NOW AT START 



The d shown at the lower, right-hand corner of the screen also indicates that you are currently in 
the Debugger. 

The Debugger prompt is a >. When this screen and prompt are displayed, you can type Debugger 
commands on the last line with the prompt and cursor. Enter each command by pressing the 
(Return) . (ENTER) , or ( Select ) ( ( EXECUTE ) ) key. Note that the CONT key resumes normal program execu- 
tion. When execution of the program is complete, control returns to the Main Command Line. 
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Single-Stepping a Program 

When the Debugger is at this starting point, it is ready to step through your Pascal program one 
statement at a time; this mode is called Single-Step Mode. (It can also do many other things, which 
will be discussed momentarily.) In the lower, right-hand corner of the screen, the Debugger also 
conveniently displays the program line number which contains the nexr statement to be executed. 
This line number corresponds to the line number given in the Compiler listing of the program. 

For instance, when debugging our example program, line number 68 is initially displayed. This is 
the line that contains the Pascal statement that will be executed the next time you press the STEP 
key. Press the STEP key once and note that the line number changes to 69, which is the line number 
of the next statement to be executed. 

Pressing STEP a second time results in no change in line number. This response is due to the fact 
that the Debugger steps through the program one statement at a time, not one line at a time. 
Pressing STEP a third time changes the line number to 70. 

Slow Program Execution 

The Debugger also allows you to execute a program at a rate of about two statements per second. 
Press ( CTRL ) -STEP to use this execution mode (Slow-Step Mode). Line numbers are flashed on the 
screen as each is encountered. You can return to Single-Step Mode by pressing the STEP key. 

Returning to the Debugger Command Screen 

You may have noticed that the Debugger prompt disappeared when you began stepping through 
the program. Instead, the Debugger displays the screen that will be used for the program's output 
so that you can see what the program is doing at each step of execution. 

Note that any keys pressed while in this mode appear in the system's type-ahead buffer, not in a 
Debugger command line. This action allows you to type in responses to any input statements in the 
program as you would normally type them in. The program reads this buffer when an input 
statement is encountered and executed. 

At some point in the program's execution you ma y want to to r et urn to t he Deb ugger command 
screen to execute a command. To do so, press ( CTRL j - fBreaiT) ( ( CTRL ) - (PAU§I) ). The Debugger 
restores the last Debugger command screen, which is the one that you saw before you began 
single-stepping the program. You can then execute Debugger commands or return to the program 
screen by stepping through the program with the STEP key. 

Toggling Between Screens 

While in the Debugger com mand m ode, you can also toggle between these displays (without 
changing modes) by pressing [ CTRL ) -ALPHA. For example, suppose you want to quickly check the 
program screen to see last line displayed by the program. You can do so (without getting out of the 
Debugger command mode) by pressing ( CTRL ) -ALPHA. When you've examined all yo u wan t on the 
program screen and are ready to return to the Debugger's command screen, press ( CTRL ) -ALPHA 
again. 
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Screen Dumps 

While in the De bugger, you c an dump the c urrent conte nts of the alpha or graphics screens. Use 
either the DMP A ( ( DUMP ALPHA ~) ) key or DMP G ( (DUMP GRAPHICS) ) key, or execute a DA or DG command. 

Note that this feature is only allowed when running a program in the processor's "user" state 1 . It is 
not possible while executing programs in "system" state. If attempted while disallowed, no dump is 
performed and the following message is displayed: 

NOT ALLOWED NOW 

A Look at the Queue 

At this point, you may want to continue stepping through the program and noting the order of 
execution of lines. You can also get a log of all Pascal program lines executed thus far by the 
Debugger by executing the Queue command. (Actually, these are the line numbers of Pascal 
statements executed thus far.) Here is an example of the results of this command (assuming that we 
have only pressed the STEP key three times in our example): 

>Q 

206144" G9 

2061 BO* 69 

206176" 68 

206188- 67 
5TART 

The line numbers are shown in the right column. (The six-digit numbers in the left column, each 
followed by ' , are memory addresses for use when debugging Assembler language programs; you 
don't usually need to be concerned with them while debugging Pascal programs.) 

Note that the line numbers in the queue are in reverse order of execution: the first line executed is at 
the bottom of the queue listing, the second is listed above the first, and so forth. Also note that the 
line at the top of the list has nor yet been executed; it will be executed the next time the STEP key is 
pressed. 

Note that Pascal line numbers will only be shown if the $DEBUG ON$ Compiler option was used. 

Note also that when the question RESTART WITH DEBUGGER? is displayed after e n counte ring 
an exception that was not trapped, you can get a listing of the queue by pressing ( CTRL ) - ( Break ) and 
then executing a Q command. You can also direct the Debugger to trap exceptions, as described in 
the Exception Trapping section of this chapter. 

Displaying Data 

Before showing how to use many of the more powerful Debugger features, let's look at some 
simple Display operations. Execute the following command: 

>D 8+32 

+ 40 

1 All user programs are executed in the "user" privilege state, while system programs, such as the Editor, Filer, and so forth, are executed in 
"supervisor" privilege state. See the MC68000 User's Manual for a more comprehensive description of these states. 
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From this example, you can deduce that the literal numbers that you entered were interpreted as 
decimal integers and that the result was a signed decimal integer. 

Note that you don't need to specify the D in commands that begin with non-alphabetic characters. 

>8 + 32 

+ 40 

Now execute this command: 

>D -327BB-327G8 
-G553B 

From this result, you can see that the range of integers is at least 16 bits. In fact, it is 32 bits, which 
indicates that a four-byte register could be used to store the numbers and results. The range is - 2 31 
through 2 31 - 1 (or 2 147 483 648 through 2 147 483 647). 

Executing these commands might help to see this range of integers more clearly: 

>D 127*25G*25G*25B 

+2130706432 

>D 128*256#25B*256 

OVERFLOW 

Note that only integer arithmetic operations are performed. For instance, division produces the 
integer portion of a quotient: 

>5/3 

+ 1 

Display Formats 

Since the Debugger uses the processor's 32-bit registers for expression evaluation, most results are 
formatted using four-byte quantities. Here are two equivalent examples of using the default format 
of one signed (four-byte) INTEGER: 

>D 255 

+ 255 
>D 255:114 

+ 255 

The format specifier is the ':1I4' appended to the literal number 255: the leading 1 indicates that 
one quantity is to be generated; the I indicates that the quantity is to be displayed as a signed, 
decimal Integer; the trailing 4 indicates that 4 bytes are to be formatted. 

If the default format of one four-byte decimal integer is not what you'd like, you can explicitly 
specify another format. For example, the following command generates four one-byte Binary 
numbers (the ! 's indicate binary notation): 

>D 1 024+255 :4B1 

100000000 100000000 100000100 111111111 
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Here is an example of formatting the integer into four one-byte octal numbers (the %'s indicate 
Octal notation): 

>D 1024+255:401 
10 10 14 Z377 

Now specify that the number is to be formatted as one four-byte hexadecimal number with either of 
the equivalent commands (the $'s indicate hex notation): 

>D 1024+255: 1H4 

$000004FF 

>D 1024+255 :H 

$000004FF 

The leading 1 and trailing 4 are the defaults assumed when these parameters are omitted. 

This format specification directs the Debugger to display two bytes as a hex value: 

>D 1 024 + 255 :H2 
$0000 

Note that 0's were displayed because the Debugger begins with the mosf-significant bits of the 
four-byte integer. Here is a more meaningful display format for the same data: 

>D 1024+255:2H2 
$0000 $04FF 

It is also possible to display literal strings with the data you are formatting for the display. Either 
single or double quotes can be used to delimit the string. For example, this command gives a more 
descriptive display: 

>D -7: '-7 in Hexadecimal = ' »H4 
-7 in Hexadecimal = $FFFFFFF9 

You can also disassemble machine-language instructions by using the X format specifier. Here is an 
example: 

>D $4E750000:X 
RTS 

This is usually only helpful while debugging Assembler-language programs. (Note that you must 
load module REVASM into memory with the P-load command from the Main Command Level in 
order to use this format. ) 

Another format specifier is the slash (/). When a "/" is encountered in a Display command, the 
display is continued on the next line. 

>D 23 + 45:/ > 'RESULT = ',14/ 
RESULT = +G8 
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Input Formats 

The ! , 1, and * symbols preceding numbers in the above examples were used to indicate the base 
of the numbers displayed on the screen. Similarly, you can use them with literal numbers input in 
the command. This feature allows number-base conversions. 

For example, suppose that you want to convert the binary number 11001010 to its decimal 
representation. Here is a sample command: 

>D ! 11001010: I 
+ 202 

To convert the number to hex, execute this command: 

>D !00110110:H 
40000003G 

Changing the Default Display Format 

The default format can be changed by giving an F (Format) command. For example, the following 
command changes the default to ':1H4\ which instructs the Debugger to take 4 bytes and display 
them as one four-byte Hexadecimal value: 

FH 

This command sets the default format to Octal (':104'): 
F0 

This command sets the default format to Binary (':1B4'): 

FB 

This command changes the default format to ':1U4', which directs the Debugger to display 1 
four-byte Unsigned decimal integer. 

FU 

This command sets the default format back to signed decimal Integer (114): 

FI 

Now that you've had an introduction to the Display commands, let's look at some more powerful 
commands. 

Controlling Execution with Breakpoints 

A breakpoint is a point in the program where you want execution to be temporarily halted. With a 
Pascal program, the point will be at a program line. Thus, when the Debugger is executing a 
program and encounters a breakpoint, it halts just before executing the program line. 
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Setting Breakpoints 

To set a breakpoint, use the BS command. Specify the location as an integer which follows the 
letters "BS", separated by a space. For example, to set a breakpoint at Pascal program line 74, 
enter the following command: 



BS 74 

Press CONT (CONTINUE) and the program begins executing again. When it encounters line 74, it 
pauses before executing the line and displays the message: 

NOW AT LINE 74 

The Debugger then prompts you for another command. At this point, you can do any of the 
following: 

• Step through the program one line at a time (if it was compiled with $DEBUG ON$) 

• Execute other Debugger commands (such as examine memory or register contents) 

• Continue the program 

Once the program has finished execution, all breakpoints are automatically de -activated. You will 
have to explicitly re-activate them, as described in a subsequent section. 

Up to nine such breakpoints may be defined at one time. Most breakpoints remain in effect until 
cleared or de-activated. 

The Count Option 

An optional count can be included by adding an integer after the location. The count instructs the 
Debugger to stop when it reaches the location the indicated number of times. For example, enter 
the following command: 

BS 31 3 

This particular command instructs the Debugger to halt the program immediately before the third 
execution of line 31. Press CONT, and the program executes until line 31 is reached the third time 
and then halts. Note that this type of breakpoint is automatically cleared when encountered the 
specified number of times. 

Breakpoints with Commands 

Another form of the BS command is the "BS" and the location number followed by a Debugger 
command string enclosed in quotes. The command string is one or more legal Debugger com- 
mands (separated by semi-colons). These commands are immediately executed when the location 
is encountered. The Debugger automatically continues program execution after executing the 
command string. Here is an example that will provide a visual record of how many times that line 
37 was executed: 

BS 37 "D 'LINE 37 REACHED.'" 

Of course, you will need to get back into the Debugger command screen to see the results of this 
breakpoint being encountered. The D (Display) command is explained in detail later. 
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You can alternately pause the program by making the last command in the string a question mark. 
This command directs the Debugger to pause and wait for input from the keyboard. For example, 
enter the following command breakpoint: 

BS 59 "D PC! ?" 
The Debugger stops at line 59, displays the Program Counter, and waits for input. 
Here is another example of using a breakpoint with a command: 

bs 59 'if 1 = 1 ; d "i = i"; else; d " 101" ;?; end' 

The relational expression following the IF command, in this case 1 = 1 , is first evaluated. If it is true, 
then the command(s) between the IF and the ELSE are executed. If it is false, then the command(s) 
between the ELSE and END are executed. This type of command is useful for purposes like 
checking the value of a variable and then pausing if its value is out of an expected range. The IF, 
ELSE, and END commands are further explained in the reference section. Checking the value of 
variables is explained later in this tutorial. 

Deactivating Breakpoints 

The BD command deactivates breakpoints. If a line number is included, the breakpoint is deacti- 
vated for that line number. For instance, the following command deactivates the breakpoint at line 
41: 

BD 41 

If no line number is included, all breakpoints are disabled. For example, this command disables all 
breakpoints: 

BD 

Displaying the Breakpoint Table 

The B command displays the breakpoint table or the one at the specified line number. Execute the 
following command: 



and you'll see a display similar to the following: 

>B 

BREAK POINTS 

A 74 

A 37 D 'LINE 37 REACHED' 

A 59 D 'IF 1 = 1 ID "1 = 1" ! ELSE 5 D "KM" !? 5 END 

The first character on each line of the table is either "A" for active, or "D" for deactivated. The 
second parameter is the line number of the breakpoint. If the third entry in the table is a positive 
number, then a count option is in effect for the breakpoint (execution will pause when the Debug- 
ger reaches the line that number of times). If the third entry is a command string, then that 
command is executed each time the line is encountered. If it is a "0", then it is a normal breakpoint 
(i.e., no count nor command was specified with the breakpoint). 
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Reactivating Breakpoints 

The BA command reactivates disabled breakpoints. If the line number is included, the breakpoint is 
reactivated for that line number, otherwise, all breakpoints are affected. For example, the following 
command reactivates the breakpoint that was deactivated in the example above: 

BA 41 

Try the B command to see the table again. 

When a program runs to completion and is then restarted (by pressing the ( D ) key), the 
breakpoints are still there; they are just deactivated. Use the BA command to reactivate some or all 
breakpoints. 

Clearing Breakpoints 

The BC command clears breakpoints by removing them from the table. If a line number is 
included, the breakpoint is removed only for that line; otherwise, all breakpoints are cleared. Enter 
the following command to remove only the breakpoint at line 41: 

BC 41 

The Pause Function and Breakpoints 



If the Debugger is not installed, the [ Break ) ( (PAUSE) ) key is a no-op. The rest of this discussion 
assumes that the Debugger is installed. 



While not in the Debugger command mode, pressing ( Break ) effectively halts any program at the 
current execution point. (Note that this key may not pause the program on a line boundary like the 
STEP key does.) 

While in the Debugger command mode, however, pressing ( Break ) returns you to the user program 
display and pauses the program at the current execution point. Press continue to finish program 
execution. 



If you press ( Break ) after encountering an active breakpoint, it will also get you to the program's 
display. However, if you pause exactly on a currently active breakpoint (but before encou ntering 
it), pressing ( Break ) will not get you into the program's display. You would have to press [ Break ) 
again cause the breakpoint to take immediate effect. CONT will then work as expected. 

Executing a Number of Statements 

Go commands set a tenth temporary breakpoint. They are one-time commands to pause execution 
before a specified program instruction. 

The G command tells the Debugger to Go. If you include a number after the "G", that number of 
statements is executed, after which the Debugger halts and waits for another command. For 
example, this command tells the Debugger to Go 8 statements: 

G 8 
If no number is given, the remaining instructions are executed (same as pressing CONT). 
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The GF (Go and Flash) command is the same as the G command except execution is slowed and 
line numbers are flashed in the lower right corner of the screen. 

The GT (Go Til) command is the same as Go except a location is specified rather than a count. For 
example, this command tells the Debugger to Go 'Til line 39 is reached: 

GT 39 

Another form of this command tells the Debugger to Go Til the location is reached a number of 
times. For example, the following command tells the Debugger to stop before line 41 is executed 
the third time. 

GT 41 3 

The GT statement also allows the command string option. For example, this command directs the 
Debugger to do the following: execute the program until line 42 is reached, then display the 
Program Counter and await further instructions. 

GT 42 "D PC! ?" 

The GTF (Go Til and Flash) command is the same as GT except execution is slowed and line 
numbers are flashed in the lower right corner of the CRT. 

Tracing Program Flow through Procedures 

You can also halt execution of a program as it enters and exits procedures. For instance, suppose 
that you want to halt the program when the current procedure is exited. To do that, execute the PX 
(Procedure eXit) command: 

PX 

Execution will be halted after the procedure is exited (i.e., after the last line of this procedure is 
executed, but before the subsequent program line is executed). For instance, executing this com- 
mand while in Level_3 results in this display: 

>PX 
PROC EXITED 

The Debugger shows that the next line to be executed is line 31. 

To halt the program at the point that the current procedure (or main program) calls another 
procedure, use the PN (Procedure Next) command: 

PN 

When the next procedure is encountered, the Debugger reports this message: 
NEXT PROC 

and the program is halted before executing the first executable line of the procedure. If the current 
procedure is exited before another is called, the Debugger reports this message: 

PROC EXITED 
and the program is halted before the next executable line of the calling procedure is executed. 
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A Look at the Stack Frame 

Another handy feature to use while walking though the program on a procedure basis is the SF 
(Stack Frame) command. Here is an example display of this command: 

>SF 

59 LEVEL- 1 
PROC ADDRESS -40331G" 
CALLED FROM -402718- 
LINE 74 

The first line of the display shows the first (executable) line of the program next to the procedure's 
name. The second line shows the memory address of the procedure (which is not important while 
debugging Pascal programs). The third line shows the address of the procedure. The fourth line 
shows the number of the line from which this procedure was called. 

Examining Variables 

Without the ability to check the value of program variables, debugging a program could become 
more tedious than it already is. Rest assured that this Debugger does allow you to look at the 
contents of any variable in computer memory. However, in order to check the contents of program 
variables, you will need to know two important facts: where they are in memory, and how to format 
them into an understandable form. 

To see where a variable is stored in memory, it is necessary to look at the Compiler listing. Each 
variable has a negative integer printed next to it on the listing. This negative value is the offset (in 
bytes) from the base address where the variables are located. The base address for a procedure's 
local variables is the current stack frame pointer (SF); the main program's variables have a base 
address offset the value of the program name (here XYZ) from A5. 

That's why it's helpful if, when writing the program, you declare each variable on a separate line so 
that an offset will be printed on the listing for each variable. Alternatively, you can use the 
$TABLES$ Compiler option to get a printout which tells all about each data type and variable. This 
option is explained further under "Structured Variable Formats". 

To format the variable's value in memory, you will need to use the Display command. Let's go back 
to the example program and let it finish by clearing the breakpoints using "BC" and then press 
CONT. Restart the program and then execute GT GO command to Go Til line number 60. 

To see the value of the local variable i that is declared in the procedure called LeveLl, look at the 
Compiler listing (line 14) to see that it has an offset of — 4. This is an offset from the stack frame 
pointer (SF) of that procedure. Subtract 4 from the stack frame pointer, and use "'" after the 
expression to indicate you want the contents of the memory location referenced by the value of the 
expression in parentheses. Enter the following command: 

>D (SF-4) - : ' X = ' tl 
X = 

To see the value of y, execute: 

>D (SF-8) * : ' Y = ' »I 
Y = 
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And to see the value of z, execute: 

>D (SF-12)-: ' Z = ' »I 
Z = 

You may also specify that all three integer variables be displayed at the same time by executing this 
command: 

>D (SF-12) *: 3 


The display will show the three integer variables separated with spaces. The variable with the offset 
of - 12 will be the first one displayed, the one with the offset of - 8 is second, then the third one 
has offset - 4. 

When looking for local variable values, be sure that you have stopped the program in the proce- 
dure that defines the variables. Each procedure that is called has a stack frame created for it even if 
there are no local variables. If you have stopped the program in a procedure which is contained 
inside of another procedure, you can use the walk commands to get to the stack frames of the outer 
level procedures (see "Static and Dynamic Links"). 

The global variables in the main program or globals declared in modules are located at offsets from 
their specific global area. The respective areas have a symbol associated with each one. The symbol 
has a value which is equal to the offset or distance from (A5). So when you reference these 
variables, add the program or module name to A5 and then subtract the offset for the particular 
variable location. 

For example, if you wanted to see the value of the variable x in the main program (here it is named 
XYZ), use this command: 

D (A5+XYZ-4)* 

To see the value of Y, execute: 
D (A5+XYZ-8) A 

To see the value of the two character variables in chl and ch2 (of program DEBUG), it is necessary 
to specify a format, because the default format is integer. To see the variables chl and ch2, execute 
this command: 

D (A5+XYZ-2B) * :2A1 

The format specifies that 2 Alpha values are to be displayed, each having 1 byte. They are located 
at an offset of -26 from the value of symbol XYZ, relative to A5. 

The processor registers that can have their values displayed are listed below: 

Address registers) 
Address registers) 
Data re Sisters) 
Data registers) 

ProSraw Counter) 
Status register) 



A0. .A7 


(the 


AA 


(Al 1 


DO. ,D7 


(the 


DD 


( all 


PC 


(the 


SR 


(the 
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To display the numeric values of the contents of address register A0 and the Program Counter, 
execute this command: 

D AO PC 

To display the numeric value at the location referenced by the the Program Counter (i.e., whose 
address is stored in the PC), execute the following command: 

D PC" 

To display the value at the location referenced by the Program Counter, interpreting it as an 
Assembler language instruction, execute this command (remember that module REVASM must be 
P-loaded to use this format): 

D PC":X 

The Debugger symbols and corresponding definitions are as follows: 

LN (Line N urn be r > 

EC (Escape Code) 

10 (I/O result code) 

GB (the Global variable Base) 

RB (the code Relocation Base) 

SF (the current Stack Frame pointer) 

Examining Consecutive Memory Locations 

The Open command is like the Display command except the address is displayed with the value 
and you are prompted to press either the up-arrow key or the down-arrow key. This causes the 
address value to increment or decrement depending on the key choice. The adjustment is 1 byte 
with the OB command, 2 byte s with th e OW com mand a nd 4 byte s with the OL command. When 
you have seen enough, press ( Return ) , (ENTER) , or ( Select ) ( ( EXECUTE ) ) to terminate Open mode and 
return to the Debugger command mode. For example, to see the hex values which are the machine 
codes for the current program, use this command: 

FH 

(See the Default Formats section for more details.) 

To examine (16-bit) word pointed to by the current contents of the Program Counter, use this 
command: 

OW PC" 



The > to the right of the display prompts for an up-arrow key ( ( f ) ) or down-arrow key 
( ( I ) ). To s ee the nex t word in memory, press the up-arrow key. Continue until you have seen 
enough. Press ( Return ) or (ENTER) to exit the Open command. 
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Formats for Structured Variables 

There is a mechanism for displaying non sequential values also. It is necessary to specify one 
memory location to set the memory pointer. Then by using special symbols, you can alter the value 
in the memory pointer. You can also display the value of the memory pointer. All these symbols are 
part of the format and are typed following the location specification and a colon (:). 

"*" is the u a 1 u e of the memory pointer 

"<" preceded by a number* decrements the value of the memory 
pointer by the number 

">" preceded by a number* increments the ualue of the memory 
pointer by the number 

"'"" causes the memory pointer to taKe the ualue at the 
location indicated by the current pointer 

These mechanisms make it possible to examine different fields of structured variables. 

First, a note about structured variables. When space is allocated for a structured variable, the 
number of bytes needed is determined and given to the variable. The individual elements of the 
structure are then assigned space at ascending locations. For example, if you had the following 
Pascal record, 14 bytes are needed to store the whole record: 

Pasc.Rec = RECORD 

x : INTEGER! 

y : INTEGER! 

chl : CHAR! 

ch2 : CHAR! 

pointer : A Pasc_Rec5 

end; 



If a variable of this type is the first variable for a procedure, then the record would occupy the first 
14 bytes below the stack frame pointer (SF-14) A . The elements in the record would be at positive 
offsets from this location. Variable x would have an offset of (SF-14P; y has an offset of 4 
(SF-14 + 4P; Chl has an offset of 8 (SF-14 + 8)*; etc. This information is easily obtainable when 
the $TABLES$ Compiler directive is used. 

The following drawing illustrates the structure of the RECORD variable in memory. 
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Rather than displaying the values of the record individually, you can use the following Debugger 
command: 

D <SF-14) " : 14 .4> >2A1 »'• ,4> »ia »* 

This command tells the Debugger to go to the memory location 14 bytes below the Stack Frame 
pointer (the bottom of the record), display the four-byte integer (x), go up 4 bytes and display the 2 
Alpha characters, assume the value that is stored after the characters (the pointer field), then go up 
4 bytes in the new record and display the four-byte integer (y), and then display the current 
location. Notice that the Debugger display pointer is left at the subsequent locations after the 
particular displays are made. In other words, after the display of (x), it is only necessary to move 4 
bytes rather than 8, to position the display pointer to the character variables. 

Changing Memory Contents 

The ability to change the values in memory is, among other things, the ability to get a program back 
on the right track. In one Debugger session, you can detect several problems with a program 
without having to stop, edit and recompile the program for each one. Simply change the values of 
the variables that are causing the problem. To change the values of variables in a Pascal program, 
use the Open commands. Variables are referenced the same way they are with the Display 
command. 

The Open commands are as follows: 

• OB - for byte values. 

• OW - for word values. 

• OL - for long word (four-byte) values. 

Suppose you want to change the value of a variable to 8; assume that it is local to the current 
procedure, that it is an integer variable, and that it has an offset of -4 from the procedure's stack 
frame pointer (SF). It is necessary to use the OL form of the Open command, since integers are 4 
bytes long. Execute the following command: 

OL (SF-4K 8 

As another example, suppose you want to change the value of the global (main program's) variable 
chl to "x". Because characters only use 1 byte of storage, use the OB form of the command. 

OB (GB-25)" "x" 
By changing the values of those variables, the sequence of execution is drastically altered. 
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Static and Dynamic Links 

Each time a procedure is called in a Pascal program, a new stack frame is created. This stack frame 
contains all the local variables in the procedure as well as the procedure's static and dynamic links 1 . 

The Debugger contains a mechanism for following these links. It is the Walk command. The Walk 
command takes three forms: 

• WS - follows the static link back one step. 

• WD - follows the dynamic link back one step. 

• WR - resets to the current stack frame. 

There are no options or parameters. These commands in no way affect or influence program 
execution. 

Restart the Debugger by pressing the ( Stop ) key and the ( D ) key. Set a breakpoint on line 31 for 
the third execution of the procedure Level_3. 

BS 31 3 



Press (Return) or (ENTER) , and then press CONT. The program will stop the third time line 31 is reached. 

The sequence of calls is as follows: 
Program XYZ 

Procedure Leue 1_1 

Procedure Level _2b 

Procedure Level_2a 

Procedure Leu e 1_3 

Procedure L e u e 1 _ 3 

Procedure Leuel_3 

Give six successive WD (Walk Dynamic) commands and you'll get the above information pre- 
sented in reverse order. The information displayed for each WD command is the stack frame 
information for the current procedure and then the same for the calling procedure. The stack frame 
pointer is updated to point to the calling procedure's stack frame. You can look at those variables 
and the links stored in that stack frame. Consecutive WD commands walk us back through the 
entire calling sequence. We can stop anywhere along this path and examine the variables in a 
procedure's stack frame. 



1 Static and dynamic links are described in detail in the section of the Compiler chapter called How Pascal Programs Use the Stack. 
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To return to the stack frame for LeveL3 where you stopped the program, execute a Walk Reset 
command: 

WR 

This command resets the Debugger stack frame pointer variable. 

You can also walk the static link. This gives you the ability to examine variables whose scope 
includes the current procedure. Execute: 

ws 

This command brings us to the Stack Frame for Level_2a which contains the variables i, x, and y. 
Use the Display command to examine the value of i. 

D (SF-4P 

The value of i is displayed. 



The value of i is only affected by successive executions of Level_3. If Level_3 had local variables, 
they would display different values in each stack frame. However, only one copy of the variable i 
exists in the one stack frame for procedure Level_2a. The value of i is as it was when we stopped 
program execution during the third invocation of LeveL3. That value is 3. 

Exception Trapping 

It is possible to stop execution of a program at an exception to normal processing. Normally, an 
escape is made by the system and successive recovery mechanisms allow termination of the 
program. At the time of termination, the system displays the escape code and the line number in the 
outer level recovery. The escape code is valid information, but the line number may not be the 
location of the error. By re-executing the program with a trap set for the exception, we can stop 
execution at the point of the error, have the actual line number of the error displayed, and examine 
variables for the problem. 

There are three commands for exception trapping. We can trap selected escape codes with the 
Escape Trap instruction. The following command directs the Debugger to trap only escape code 
100. 

ET 100 

When escape code 100 is encountered, control is returned to the Debugger and the following 
message is displayed on the screen: 

-EXCEPTION- 
ESCAPE CODE 100 
SR=$0000 PC= -207532 LINE +12 

We can stop at all except selected escape codes with the Escape Trap Not instruction. This 
command directs the Debugger to trap every escape code except 100. 

ETN 100 
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Not specifying an escape code causes the command to work for every escape code. This command 
directs the Debugger to trap all escape codes. 

ET 

This command doesn't trap any exceptions. 
ETN 

When the exception occurs, execution stops and control is transferred to the Debugger. At that 
point, you can examine the state of the program. 

When the Debugger is initiated, the default escape trapping command is the following: 

ETN -Z0 



These are the escape codes for normal termination and the ( Stop ) key. The Debugger will trap all 
escape codes except those. 

The third type of escape trap command allows you to execute command(s) when the escape is 
detected. Here is an example: 

ETC 'D "ESCAPE HAS OCCURRED"!?' 

This command displays its message and then halts the program, awaiting further Debugger com- 
mands. 

Generating Escapes 

With the Debugger, you can also generate escapes. For instance, this command generates an 
ESCAPE(IO) at the current point in the program. 

>EC 10 

The result of this command is the same as if the program had encountered the escape at the current 
location. If you have an ET command currently defined for the escape code, the Debugger will trap 
it also. 

A Note about Assembly Language Programs 

All of the Debugger commands apply when debugging an Assembler language program as well. 
The difference is that the location specification is given as an address and not a line number. An 
address is specified with a " ~ " appended to the location specifier. For example, the following 
command says to Go Til the address FFFF 1423 is encountered: 

GT FFFF1423" 
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The Debugger knows about symbols which have been DEFed. The entry points into assembly 
modules, programs, and procedures should have been defined (with DEF). You can specify an 
address in an assembly routine by specifying an offset from the routine's entry point. The offset in 
the routine can be found on the Assembler output. For example, the following (equivalent) com- 
mands direct the Debugger to Go Til encountering the the address 16 decimal (10 hex) memory 
locations past the entry point into "routine": 

GT < routine + lG) " 

or: 

GT ( routine+$10) A 

Read about the particulars of each command in the subsequent Command Reference section. 
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Debugger Keyboard 

This section describes the key definitions while in the Debugger. Note that once you are in the 
Debugger there are two modes: Command Mode and Step Mode. 

A Note about Key Notations 

Throughout this section, you will be shown which keys invoke certain Debugger functions. Since 
you may have one of three different keyboards connected to your computer, each with a different 
set of keys, you will need to learn which key to press on your keyboard. Here are examples of keys 
used to invoke a few functions on the three different keyboards. 1 



Desired 


HP 46020A 


HP 98203B 


HP 98203A 


Function 


Key(s) 


Key(s) 


Key(s) 


Pause 


( Break ) 


f PAUSE) 


( PSE) 


Single Step 


((System)) ( fs ) 


( STEP ) 


( STEP ) 


Slow Step 


((System)) ( CTRL )-( /5 ) 


( CTRL)-( STEP) 


( CTRL)-( STEP) 


Continue 


((System)) ( f\ ) 


( CONTINUE ) 


( CONT ) 



For instance, invoke the Pau se fun ction on a 46020 keyboard by pressing t he ( Break ) key. On a 
98203B keyboard, press the (PAUSE) key. With a 98203A keyboard, press the ( PSE ) key. 

As another example, suppo se tha t you want to invoke the Single-Step function. On both 98203A 
and B keyboards, press th e ( STEP ) key; the label is on the key itself. On a 46020 keyboard it will be 
the System key labeled ( /5 ) on the key, which is labeled STEP on the screen while in the 
System -key mode. (If you are no t already in System-key mode, then you will need to press the 
(System) key before pressing [ f5 ) ). The sam e notation is used for the other System keys on the 
46020 keyboard (i.e., ( f\ ) through ( ft ) ): the actual System key is not given in text; the label is 
given instead. You will need to make the association, which yo u can easily do by looking at the 
System-key labels while the Menu is bei ng disp laye d (pres s the [ Menu ) key to toggle the Menu on 
and off). If you are not familiar with the (System) and ( Menu ) keys, read the discussion in the Pascal 
User's Guide. 

The convention used in this manual is to sho w the 4 6020 k eys first (followed by the equivalent 
98203B key in par enthes es). For instance, the ( Break ] ( (PAUSE) ) key in vokes the Pause f unction : on 
the 46020, it is the fBreaiT) key; on a 98203B ke yboard , it is the ( PAUSE) key. (The 98203A ( PSE ) key 
is not shown, because it is close enough to the (PAUSE) label that you should be able to easily make 
the connection. ) 

Is the Debugger Installed? 

Before proceeding, you should verify that the Debugger is currently installed. Press ( Break ) ( (PAUSE) ) 
to pause the system. If a p is dis played in the lower, right-hand comer of the screen, then the 
Debugger is installed. Press CONT ( ( CONTINUE ) ) to resume operation. 



If the Debugger is not installed, then pressing ( Break) will do nothing. 



1 This discussion only gives a few examples; the Debugger Keyboard section near the end of the chapter describes all key(s). 
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Calling the Debugger from the Main Command Level 

( D ) From the Main Command Level, pressing the ( D ) key calls the Debugger 

(if installed). 

Step Modes 

Here are the available operations and key definitions while in the Debugger Single-Step and 
Slow-Step Mode. 

Getting into the Step Modes 

STEP Causes the program to halt on the next line number; or, if already halted, 

execute one Pascal statement. (This key gets you into the Single-Step Mode. ) 



( CTRL ) -STEP Causes program execution to be slowed (to about 2 statements per second) 

and line numbers displayed. (This key gets you into the Slow-Step Mode.) 

Contr olling Program Execution 

(Break) Program execution is paused. Note that the type-ahead buffer is still active 

( (PAUSE] ) and immediate-execute keys still function (e.g,. DMP A). 



( Stop ) Stops program execution. 

Getting into C ommand Mode 

( CTRL ) - ("Break"] This key provides immediate entry into Debugger Command Mode. 

( ( CTRL ) - ( PAUSEl ) 

Returning to the Main Command Level 

CONT Causes program exection to resume with Step mode cancelled. 

( (CONTINUE) ) 

Command Mode 

Here is a description of available operations and key definitions while in the Debugger Command 
Mode. If it is not installed, the command is identical to the eXecute command. 

Entering Commands 

Alphanumeric Keys Used to enter Deb ugger commands. The characters generated are upper- 
case; you must use [ Shift ) to produce lowercase characters. 



( Return ) or (ENTER) Terminates input and initiates execution of the command. 

(Select ] Terminates input and initiates execution of the command. 

( ( EXECUTE ) ) 
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fcfRLl -ALPHA 



[ Caps ) 

( Shift ) with 
numeric-pad keys 



( CTRL ) with 
alphanumeric and 
numeric-pad keys 



c 



J 



( Clear line ) or 
[Delete line) 
( CLRLN ) or 
[DEL LN) ) 

RECALL 

[ Insert char"! 
( [ INS CHR ) ) 

[Delete char) 
( [ DEL CHR ) ) 

CLR-END 

( [CLR->END] ) 



( /1 ) thru [ 11 } 
( fin thru CKJ) 

Knob 

[ Shift ) -Knob 

Left-arrow and 
Right-arrow 

Up-arrow and 
Down-arrow 



Alternates between the Debugger command screen and System screen 
( rc^RLl - fExIcl on the 98203A keyboard). 

Undefined (keyboard is always in CAPS mode). 

Produces special characters (only 46020 keyboards). 

Allows entry of ASCII control characters. 



Back space the cursor and blanks one character (If the cursor is in the 
extreme left, this key is a no-op). 

Clears the input line. 



Clears the input line and recalls the last executed line. 

Inserts one (1) blank character at the cursor position (does not switch to an 
"insert mode," as there is none). 

Deletes the character at the cursor position. 

Deletes all characters to the right of the cursor. 

Typing-aid keys (explained under K commands). 

Same as left/right arrow keys. 

Same as up/down arrow keys. 

Move the cursor in the corresponding direction. 

Have meaning only with the Open commands (OL, OW, OB). 
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Screen Cont rol 

( Clear display ) 
( ( CLR SCR ) ) 

ALPHA 



DMPA 

( ( DUMP ALPHAl ) 



Clears the alpha raster. In Step Modes, this key clears the System screen; in 
Command mode, it clears the Debugger Command screen. 



(CTRL) -ALPHA 

GRAPH 

( (GRAPHICS) ) 

DMPG 

( (DUMP GRAPHICS) ) 



Turns on the alpha raster and turns off the graphics raster ( ( SHIFT l - fRcT] on 
the 98203A keyboard). 

Performs a DUMP A LPHA f unctio n (the current alpha raster is sent to the 
PRINTER: volume). ( fsW] - flNSCl on the 98203A keyboard). 

Alternates between the Debugger and System screen images ( ( CTRL ) - flXEC~) 
on the 98203A keyboard). 



Turns on the graphics raster and turns off the alpha raster. ( ( SHIFT ) - flNST ) on 
the 98203A keyboard.) 

Performs a DUMP GRAP HICS f unction (sends the current graphics raster to 
the PRINTER: volume). ( fSHW) - fDEL~C ) on the 98203A keyboard.) 



Contr olling Program Execution 

(Break ) Program execution is pauseed. Note that the type-ahead buffer is still active 

( (PAUSE) ) and immediate-execute keys still function (e.g,. DMP A). 



fStop l 



Stops program execution. 



Getting into a Step Mode 

STEP Causes the program to continue executing until the next line number is 

encountered (i.e., gets you into Single-Step Mode). 

Causes the program to continue executing slowly, and line numbers display- 
ed as encountered (i.e., gets you into Slow-Step Mode). 



rcfRU -STEP 



Returning to the Main Command Level 

CONT Causes program exection to resume with Command mode cancelled. 

( [CONTINUE) ) 
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Debugger Command Summary 

This section briefly summarizes the Debugger commands for quick reference purposes. A more 
complete description of each command is presented in the following Command Reference section. 

Breakpoint Commands 

BS - Sets a breakpoint at the specified location. 

BD - Disables (but does not remove) breakpoint(s). 

BA - Activates disabled breakpoint(s). 

BC - Clears breakpoint(s). 

B - Displays the breakpoint table. 

Call Command 

CALL - Calls the machine language routine at the specified memory address. 

Display Commands 

D - Displays the specified object(s). Objects can be specified immediately, directly, or indirectly. 

Formats describe the internal representation of the data. 
TD - Displays the command string which is defined by the softkey k4. 
TD I - Restores the initial command string to k4. 

Dump Commands 

DA - Performs the DUMP ALPHA function. 
DG - Performs the DUMP GRAPHICS function. 

Escape Code Commands 

EC - Generates the specified escape. 

ET - Sets up escape trapping of specified escape codes; Debugger halts when an escape is 

executed. 
ETC - Sets up escape trapping of all codes; Debugger executes the specified command when 

an escape is executed. 
ETN - Sets up escape trapping of all codes except those specified; Debugger executes the 
specified command when an escape is executed. 

Format Commands 

FB - Sets the default display format to Binary. 

FH - Sets the default display format to Hexadecimal. 

Fl - Sets the default display format to signed Integer. 

FO - Sets the default display format to Octal. 

FU - Sets the default display format to Unsigned integer. 

Go Commands 

G - Causes execution to resume (same as CONTINUE). 
GT - Causes execution to resume until specified location is encountered. 
GTF or GFT - Same as GT except that execution is slowed and the line numbers are flashed in 
the lower right-hand corner of the screen. 
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IF, ELSE, and END Commands 

IF - Allows conditional execution of subsequent commands based on the result of evaluating 

the specified expression. 
ELSE - Delimits the commands that will be executed when the IF condition is FALSE. 
END — Ends the IF command. 

Open Memory Commands 

OB, OL, and OW - Used to display (and optionally alter) the values of memory locations. 

Procedure Commands 

PN - Halts program execution when the next procedure is called (or when the current one is 

exited, whichever occurs first). 
PX, or P - Halts program execution when the current procedure is exited. 

Queue Commands 

Q - Displays the Queue, which is a record of which line numbers were executed (or PC values 

of instructions executed). 
QE - Ends recording of line number values in the Queue. 
QS - Starts the recording of information in the Queue. 

Register Operations 

A0..A7, D0..D7, PC, SP, US, SR - Display or assign values to the corresponding processor 

register(s). 

Softkey Commands 

kO .. k9 - Defines the command string to be displayed when the softkey is pressed (while in the 
Debugger). 

System Boot Command 

sb - The system boot command puts the computer in the power-up state for re-booting. (The 
command must be typed in lowercase letters. ) 

Trace Commands 

T- Causes the specified number of instructions to be executed, each followed by an implicit TD 

command. 
TQ - Same as the T command except that the TD command is executed only after the last 

instruction. 
TT - Same as TQ except that a location is specified rather than a count. 

Walk Procedure Links Commands 

WD - The Stack Frame pointer (SF) is moved to the stack frame of the calling procedure. 
WS - The SF is moved to the stack frame of the nesting procedure. 
WR - The SF is returned to the current stack frame. 
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Debugger Command Reference 

This section contains a formal description of syntax and semantics for each Debugger command. 

Debugger Expressions 

With the Debugger, all expressions are integer expressions. 






binary 
operator 



integer 



register 
symbol 



Debugger 
symbol 



system 

symbol 



-0- 



hex 
digit; 



octal 
digits 



■©- 

■GH 



b inary 
digits 



expression 



^H2H 



•■ address 



expression 



binary 
operator 



address 



"0 




expression 
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Item 


Description/Default 




Range Restrictions 


binary operator 


an operator that requires two operands 




<, < = , = ,> = ,>,<> 


register symbol 


a symbol representing a processor register 




A0..A7, D0..D7, PC, SP, 
US, SR 


Debugger symbol 


a symbol known to the Debugger 




LN (Line Number) 

EC (Escape Code) 

10 (I/O result code) 

GB (the Global variable 

Base) 

RB (the code Relocation 

Base) 

SF (the current Stack 

Frame pointer) 


system symbol 


any symbol in the system symbol table 




- 


address 


an integer numeric expression followed 


by a 


- 2 31 thru 2 31 - 1 




" /v ", which refers to the contents of the specified 






memory address 






size 


integer expression that specifies the number of 


1 thru 4 




bytes to be used 







The "U" (unsigned integer) and "I" (signed integer) option paths indicate whether the value at the 
specified address and with specified number of bytes (size) is to be treated as a signed or unsigned 
integer. 

Multiple Commands on a Line 

Several commands may be entered on the same line. These commands are separated by a 
semicolon (;). 



O 



1 ' I single 

Debugger command 
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Breakpoint Commands 

Breakpoints are points in a program where execution may be halted. The Breakpoint commands 
control program execution by setting up, activating, and clearing breakpoints in a program. 

B 



The "B" command causes the breakpoint table to be displayed. 





— *> 


• 




line 
number 


/ 








address 



Item 


Description/Default 


Range Restrictions 


line number 
address 


an expression that identifies a program line 

an expression, followed by a " /v ", that identifies 
a location in memory 


thru 2 16 -1 
-2 31 thru2 31 -l 



The first column contains an "A" for an active breakpoint or a "D" for a deactivated breakpoint. If 
no location is specified, the table displays all breakpoints. 

BA 

The "BA" command Activates disabled breakpoints. If a location is specified, then only that 
breakpoint is re-activated; otherwise, all breakpoints are re-activated. 



CE> 





* 


a 


line 
number 




J 






address 



Item 


Description/Default 


Range Restrictions 


line number 
address 


an expression that identifies a program line 

an expression, followed by a " /v ", that identifies 
a location in memory 


thru 2 16 -1 
-2 31 thru2 31 -l 
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BC 



The "BC" command Clears breakpoints. If a location is specified, then only that breakpoint is 
cleared; otherwise, all breakpoints are cleared. 



QT> 





» 


, 




line 
number 














w 


address 





H 



Item 



line number 
address 



Description/Default 



an expression that identifies a program line 

an expression, followed by a " /v ", that identifies 
a location in memory 



Range Restrictions 

thru 2 16 -1 
-2 31 thru2 31 -l 



BD 

The "BD" command De-activates breakpoints. If a location is specified, then only that breakpoint is 
de-activated; otherwise, all breakpoints are de-activated. 



(Z> 





» 


,i 


line 
number 




J 






address 



Item 



line number 
address 



Description/Default 



an expression that identifies a program line 

an expression, followed by a " /N ", that identifies 
a location in memory 



Range Restrictions 



thru 2 16 -1 
-2 31 thru2 31 -l 
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BS 



Setting breakpoints with the "BS" command causes the program to stop or perform some opera- 
tion at a given line number or instruction address. 



GE> 



1 ine 
number ti 



L o 



-CD- 



'_[ Debugger 

~ command 



o-> 



Item 


Description/Default 


Range Restrictions 


line number 


an expression that identifies a program line 


thru 2 16 -1 


address 


an expression, followed by a " /v ", that identifies 
a location in memory 


-2 31 thru2 31 -l 


count 


expression 


-2 31 thru2 31 -l 


Debugger command 


command (s) to be executed when breakpoint 
reached 


any legal Debugger 
command(s) 



If only a location is specified, the breakpoint is set at that location and then activated. The program 
will halt just before it subsequently reaches that point. 

Specifying a count sets a breakpoint that will halt the program after the count has been de- 
cremented to 0. (The count is decremented each time the location is reached.) When the program 
is halted, this type of breakpoint is automatically cleared. (The other two types of breakpoints set 
with the BS command are not cleared when encountered.) 



Adding a command string to the breakpoint causes the command to be executed each time the 
point is reached. A "?" in the command string causes the Debugger to wait for input from the 
keyboard. Otherwise, the command is executed and program execution resumes. 
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The Call Command 

This command is used to call the subroutine at the specified address. 



®"* 



Item 


Description/Default 


Range Restrictions 


address 


an expression, followed by a " A ", that identifies 
a location in memory 


-2 31 thru2 31 -1 



The effect of this command is as if a Jump to Subroutine (JSR) instruction was encountered just 
before the current program counter (PC). 

The CALL command can be abbreviated with the letters CA. 
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Display Command 



D 



The D command is like a print statement where the parameters are objects and formats. 



& 



-H 



expression 



str ing 



sof tkey 
symbol 



„ fc ^T*\ fc contiguous 
^ data specifi 



■o- 



address 
specif ier 



contiguous data specifier: 



^O 



Dunt -* 



n> 



cont iguous 
data specifier 




type 



L - 0" 



str ing 
constant 



*©- 



X 



contiguous 
data specif ier 



address specifier: 



^— ^ count -^ 



^O 



address 
spec i f ier 



cont iguous 
data spec i f ier 



j 



^r 



<D- 



-e- 



address 

specif ier 






cont i guous 
data specifier 
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Item 


Description/Default 


Range Restrictions 


expression 


integer expression 


-2 31 thru2 31 -1 


string constant 


literal value 


any character delimited 

with single or double 

quotes 


softkey symbol 


a symbol (not the actual key) 


K thru K 9 


address 


an expression, followed by a '" v ", that identifies 
a location in memory 


-2 31 thru2 31 -1 


count 


integer constant 


1 thru 2 31 - 1 


contiguous data specifier 


specifier that identifies the format of data which 


see drawing 




is contiguous in memory (i.e., memory pointer 


(nesting limit is 3) 




symbols * etc. not used) 




address specifier 


specifier that identifies an address in memory 


see drawing 




(memory pointer symbols such as * may be 


(nesting limit is 3) 




used) 




type 


A = Alpha character 

B = Binary 

H = Hexadecimal 

I = Integer (size = 1..4) 

= Octal (size = 1..4) 

S = String type (size is declared size) 

R = Real (size not allowed) 

U = Unsigned integer 

X = reverse assembly (size not allowed) 




size 


integer constant 


-2 31 thru2 31 -1 
(except where 
noted above) 



Objects can be immediate, direct, or indirect. 

Formats describe the internal representation of the data. Non-consecutive data can be displayed 
using the format options available when the address parameter is used. 

If a format of type S includes a count parameter, then a size parameter must also be included. 



If the o utput of a D isplay com mand fills the screen, a M ORE pr o mpt w ill be iss u ed. A rep ly of (Return) , 
( Enter ] , or (Select) ( ( EXECUTE ) ) will continue the display. ( Shift ) - ( Select"! ( ( SHIFT ) - fEXECUTE ) ) will cancel 
the display and the rest of the command string. All other responses will be ignored. 
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Dump Commands 

These commands allow you to perform the DUMP ALPHA and DUMP GRAPHICS functions while 
in the Debugger. 

DA 

The DA command performs the DUMP ALPHA function. 
C*dT)-H 

DG 

The DG command performs the DUMP GRAPHICS function. 



(lip-H 



Note 

These commands can only be used while executing programs in the 
processor's "user mode." If attempted while in "supervisor mode," the 
following error will be reported: 



NOT ALLOWED NOW 
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Escape Code Commands 

These commands allow you generate and trap escape codes while in the Debugger. 



EC 



The effect of executing this command is the same as if you had executed an ESCAPE(code) in the 
program just before the current PC. If any ET, ETC, or ETN commands have been used to set up 
escape code trapping, then the Debugger will be halted and the escape code displayed on the 
screen. 



GlH 



escape 

code 



Item 


Description/Default 


Range Restrictions 


escape code 


signed integer expression; negative for system 
escapes, positive for user escapes. 


-2 15 thru2 15 



Here is an example display: 



>EC 10 
-EXCEPTION- 
ESCAPE CODE 
SR=$0004 PC= 



+ 10 
-22B230 LINE 



+ 9 



ET 



The Escape Trap command allows you to specify that either all escape codes or specified escape 
codes are to be trapped by the Debugger. 



CE> 



I 



escape J 

code 



Item 


Description/Default 


Range Restrictions 


escape code 


signed integer expression; negative for system 
escapes, positive for user escapes 


-2 15 thru2 15 -l 



If an escape code that is in the list is encountered, execution stops and control is given to the 
Debugger. If no escape codes are specified, then processing stops for all escape codes. 



Up to 4 escape codes may be specified with the ET command. 
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ETC 



The Escape Trap Command allows you to set up command(s) to be executed when an ESCAPE is 
generated. 



GiD-C^ 



O 



Debugger 
command 



Oh 



Item 



Debugger command 



Description/Default 



command to be executed when an escape is 
encountered 



Range Restrictions 



any valid Debugger 
command 



ETN 



The Escape Trap Not command specifies that processing should stop for all excape codes except 
the ones listed. If none are listed, then processing won't stop for any escape codes. 



(^y-L 



escape 

code 



J 



Item 


Description/Default 


Range Restrictions 


escape code 


signed integer expression; negative for system 
escapes, positive for user escapes 


-2 15 thru2 15 -l 



If the program was started with the D command, then ETN -20 (which traps all except the 
( Stop ] key and normal program termination) is in effect. 



Up to 4 escape codes may be specified with the ETN command. 
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Format Commands 

The format commands allow you to specify the default display format. 

FB 

The Format Binary command sets the default format to Binary values. 

FH 

The Format Hex command sets the default format to Hexadecimal values. 



FI 



The Format Integer command sets the default format to signed Integer values. 



FO 

The Format Octal command sets the default format to signed Octal values. 

FU 

The Format Integer command sets the default format to Unsigned integer values. 
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Go Commands 

The Go commands control program execution by telling the Debugger how many lines to execute 
or the line at which to halt. 



The "G" command causes normal execution to resume. If a count option is used, that number of 
statements are executed. 



CZ> 





*■ 


, 




count 







Item 


Description/Default 


Range Restrictions 


count 


integer expression 


lthru2 15 -l 



GF 



The "GF" command is the same as the "G" command except execution is slowed and line 
numbers are Flashed in the lower right corner of the CRT. 



(Z> 



=7J 

count ' 



Item 


Description/Default 


Range Restrictions 


count 


integer expression 


lthru2 15 -l 
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GT 



The "GT" command causes execution to Go 'Til the specified location is reached. 



1 ine 
number 



address ' 



K> 



-CD- 



i— 



Debugger 
command 



o- 1 



Item 


Description/Default 


Range Restrictions 


line number 


an expression that identifies a program line 


0thru2 16 -l 


address 


integer expression, followed by a " /v ", that iden- 
tifies a location in memory 


-2 31 thru2 31 -l 


count 


integer constant 


lthru2 31 -l 


Debugger command 


command(s) to be executed when the specified 
line or address is reached 


any legal Debugger 
command(s) 



If a count option is used, execution continues until the location is reached that number of times. 

If the Debugger command option is used, the command(s) are executed when the location is 
reached. 

GTF 



The "GTF" command is the same as the "GT" command except execution is slowed and line 
numbers are flashed in the lower right comer of the CRT. 



CED-^ 



1 ine 
number 



KD-H 



-G> 



Debugger 

command 



•o-> 



Item 


Description/Default 


Range Restrictions 


line number 


an expression that identifies a program line 


0thru2 16 -l 


address 


integer expression, followed by a " /v ", that iden- 
tifies a location in memory 


-2 31 thru2 31 -l 


count 


integer constant 


1 thru 2 31 - 1 


Debugger command 


any legal Debugger commands delimited with 
single or double quotes 
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IF, ELSE, and END Commands 

These commands allow conditional execution of Debugger commands. 



Debugger 
command (s) 




■GEX 



express ion 



I fc /Q\ ,1 Debugger I, 
^\i/ command (s) 



--(else)- 



-O- 



^/XJ Debug 
^1/ comman 



gger 
Td (s) 



O 



H™> 



^^/T\_J Debug 
^J comman 



gger 
nd (s) 



Debugger command (s) : 



I O 



j single 

"^"♦i Debugger command 



Item 


Description/Default 


Range Restrictions 


Debugger command(s) 


command(s) to be executed when the sense bit 
is TRUE 


see drawing 


expression 


numeric or boolean expression whose value de- 
termines the state of the "sense bit" 


any valid Debugger 
expression 


single Debugger 
command 


one Debugger command 


any valid Debugger 

command described in 

this reference section 
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In order to better understand how IF, ELSE, and END statements work, you need some back- 
ground information. There is a sense bit that determines whether or not Debugger commands are 
executed. This sense bit is set to TRUE at the beginning of every command line. Commands on the 
line are executed as long as this bit is TRUE and skipped when the sense bit is FALSE. 

When an IF statement is encountered, the expression is evaluated. If it evaluates to non-zero or 
TRUE, then the sense bit is set TRUE. Subsequent commands are executed while this bit is TRUE. 
When an ELSE command is encountered, the sense bit is complemented (i.e., if it was TRUE, then 
it is set to FALSE, and vice versa). When an END statement is encountered, the sense bit is set to 
TRUE. Here is an example of this situation: 

>IF l = i!D 'NON-ZERO'iD 'TRUE ' iELSE iD 'ZERO'iD 'FALSE ' i END iD 'ALWAYS' 

NON-ZERO 

TRUE 

ALWAYS 

Here is an example of the converse situation. 

>IF OiD 'NON-ZERO'iD ' TRUE ' i ELSE ! D 'ZERD'iD ' FALSE ' SEND i D 'ALWAYS' 

ZERO 

FALSE 

ALWAYS 

Notice that the commands after the END statement are always executed. Note that the IF statement 
does not have to be the first command in the line. 

The ELSE command can be abbreviated as EL; the END command can be abbreviated as EN. 



The Debugger 349 



Open Memory Commands 

These commands allow you to examine, and optionally modify, the contents of memory locations. 

OL, OW, OB 



The Open Byte, Open Long, and Open Word commands are used to examine consecutive mem- 
ory locations and to assign values to the locations. 



C^H 



f OW J—*- 



address 







»■ 


—>- 


^ 










expression 














U- 


string 
constant 


J 





Item 


Description/Default 


Range Restrictions 


address 


an expression, followed by a " A ", that identifies 
a location in memory (with OW and OL, the 
address must be an even number) 


-2 31 thru2 31 -l 


expression 


integer expression 


-2 31 thru2 31 -l 


string constant 


literal 


any character delimited 

with single or double 

quotes 



Semantics 

When no value is specified after the location, the location and the contents of the location are 
displa yed and fol lowed by a special prompt. The prompt is for an up-arrow key, a down-arrow key, 
or the (Return) or ( Enter ) key. 

• The up-arrow key causes the next higher location and value to be displayed and the special 
"Open" prompt. 

• The down-arrow key is the same except that the next lower address is displayed. 

• The ( Return ) or ( Enter ) key causes termination of the "Open" prompt and a return to the 
standard Debugger prompt. 

The amount of the increment/decrement is as follows: 

• 1 byte for the "OB" command 

• 2 bytes for the "OW" command 

• 4 bytes for the "OL" command 



When the Open memory commands are used with value options, the specified value is assigned to 
the corresponding location. No attempt is made to read the corresponding memory location. 
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Procedure Commands 

These commands allow you to halt the program when a procedure is called or exited. Both of these 
commands will only work if the procedures were compiled with $DEBUG ON$. 

PN 

The PN (Procedure Next) command halts the Debugger when a procedure is called by the current 
procedure or main program (or when the current procedure is exited). 



QnJ-H 

When the current procedure or main program calls another procedure, the Debugger displays 
NEXT PROC and halts the program before executing the first line of the called procedure. 

If the current procedure is exited before another is called, the message PROC EX I TED is displayed 
and the Debugger is halted before executing the first line of the procedure that called the current 
one. 

PX 

The PX (Procedure eXit) command allows you to halt program execution when the current proce- 
dure is exited. 



©- 



When the current procedure is exited, the message PROC EXITED is displayed and the program is 
halted before executing the next line of the procedure that called the current one. Calling a 
procedure while in the current one is not reported (as it is with PN). 
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Queue Commands 

The Queue commands control and display the Queue, which is a record of the line numbers of 
statements (or memory addresses of processor instructions) encountered during the execution of a 
program. 

Q 

The "Q" command displays the addresses or line numbers and addresses of the most recent 
statements executed since a "QS" command or the start of execution of the current program. 



"MORE" is given as a prompt wh en part of the Que ue has been displayed and there is more to 
come; a reply of (Return) , ( Enter ) , or ( Select ) ( ( EXECUTE ) ) will cause the next 1..21 Queue entries to 
be displayed. Any other reply will be interpreted as another command. 

QE 

"QE" ends the recording of information in the Queue 



QS 

"QS" starts the recording of information in the Queue 
Q QS ) -h 



352 The Debugger 



Softkey Commands 

The Softkey commands allow you to define System softkeys to display literal values and com- 
mands, so that these keys will be used as typing aids. 

"KO" thru "K9" 

These commands allow you to define the softkeys as typing-aid keys; when the softkey is subse- 
quently pressed, it puts the string constant or the result of evaluating the integer expression into the 
Debugger command-input line. 



softkey 
symtjo 1 










*| 




"" 


i 


, '' 
















string 
constant 






* 


















numeric 

value 











Item 


Description/Default 


Range Restrictions 


softkey symbol 


literal symbol that denotes a softkey 


K thru K 9 


string constant 


literal value 


any characters delimited 

with single or double 

quotes 


numeric value 


integer expression 


-2 31 thru2 31 -l 



Numeric values or command strings can be assigned to the softkey symbols KO through K9 by 
typing the key symbol (not by pressing the actual key) and then typing the value to be assigned to 
the key. 

If a string constant is assigned to the softkey symbol, subsequently pressing the corresponding 
softkey will cause the literal value to be placed in the Debugger command-input line. If a numeric 
expression is assigned to the softkey symbol, the result of evaluating the expression is placed in the 
input line. 



After the command on a line is completed, pressing (Return) , (ENTER] , or ( Select ) ( ( EXECUTE ) ) causes 
the line to be interpreted. 

To see the string c onstan t or numeric value that is currently assigned to a softkey symbol, type the 
symbol and press (Return) . 
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Register Operations 
A0...A7, D0...D7, SP, US, SR, PC 

Registers can have their contents displayed or altered. If a value follows the register symbol, that 
value is assigned to the register. Otherwise, the current value of the symbol is displayed. Without 
the assignment, the command is the same as the D command. 



register 
symbol 



expression 



address 



string 
constant 



Items 


Description/Default 




Range Restrictions 


register symbol 


A0...A7, D0...D7, SP, US, SR, PC 
AA = All Address registers 
DD = All Data registers 






expression 


integer numeric expression 




-2 31 thru2 31 -l 


string constant 


any characters delimited with single 
quotes 


or double 





"AA" and "DD" cannot be used to assign values. 



System Boot 



The "sb" command places the computer in the "power-up" state for rebooting. The command 
must be typed in lowercase. 



(1T)-H 
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Trace Commands 
T 

The "T" command with count specification causes that number of machine instructions to be 
executed. A "TD" command is executed after each machine instruction. 



cz> 



count 



Items 


Description/Default 


Range Restrictions 


count 


integer expression 


1 thru 2 31 - 1 



For use with Assembly Language debugging. This command ignores address break points. 

TD 



The TD (Trace Dump) command displays the command string which is defined by the ( M ) 
( ( k4 ) ) softkey. 

CD- 




At power up, ( M ) is defined to display the PC, the instruction at (PC), the status register, the SP, 
an d all th e A (address) and D (data) registers. This display may be altered by changing the definition 

of CO 



The optional parameter "I" restores the initial definition to softkey ( /4 ) . 

TQ 

TQ (Trace Quiet) is the same as the T command except a TD command is only executed after the 
last instruction. 



C^> 



x>unt ' 



*H 



Items 


Description/Default 


Range Restrictions 


count 


Integer expression 


1 thru 2 31 - 1 



For use with Assembly Language debugging. This command ignores address break points. 
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TT 



TT (Trace Til) causes machine instructions to be executed until the specified line number or 
address is reached. TT is like TQ in that a TD command is executed only after the last statement or 
instruction is executed. 



(Z> 



1 ine 
number , , 



■-O- 1 



■©*■ 



Debugger 
command 



o-> 



Items 


Description/Default 


Range Restrictions 


line number 


an integer expression identifying a program line. 


0thru2 16 -l 


address 


an integer numeric expression followed by a """ 


-2 31 thru 31 -l 


count 


integer expression 


-lthru2 31 -l 


debugger command 


any legal commands delimited with single or 
double quotes 





For use with Assembly Language debugging. This command ignores address break points. 
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Walk The Procedure Links 
WD 

Walk the Dynamic link. This command causes the stack frame pointer to move to the stack 
frame of the calling procedure. 

f WD V- h 

WR 

Walk Reset. Brings the stack frame pointer to the stack frame of the current procedure. 



( wn ^ -h 

ws 

Walk the Static link. This command is the same as the "WD" command except that the stack 
frame pointer takes the value of the static link. This brings you to the stack frame of the nesting 
procedure as opposed to the calling procedure. Level 1 procedures have no static link. 

(wsJ-H 
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Technical Reference 



This appendix contains the following useful reference information. 

• A "System History" section that describes the additional features provided by Pascal System 
versions 2.x and 3.x 

• A discussion of file interchange between the Pascal System and Series 200/300 BASIC Sys- 
tems 

• A list of module names used by this Operating System 

• A physical memory map 

• A software memory map 
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System History 

This section first briefly describes the 1.0 version Pascal Workstation System, and then describes 
each subsequent version from the standpoint of what features have been added or changed by the 
version. It is intended to help you make the transition from earlier versions of the system to the 3.0 
system. 

Pascal 1.0 

Here is a brief description of the Pascal 1.0 System. It is put here in order to give you a reference 
point from which to begin the comparison of later systems. 

System Discs 

The Pascal 1.0 Workstation System was distributed on a set of four mini-floppy discs, plus one 
additional disc for documentation. Here are the disc names: 

BOOT: 

SYSMOL: 

ACCESS: 

COMPASM: 

DOC: 

The SYSVOL:SYSTEM.LIBRARY file contained the entire complement of IO, GRAPHICS, and 
INTERFACE modules. The unmodified BOOT: SYSTEM. INITLIB contained device-driver software 
for all peripheral devices supported by the 1.0 system. 

Documentation 

Documentation for the 1.0 system included the following five manuals. 

Problem Solving and Programming with Pascal - This is the textbook from which you can learn 
about Pascal programming, if you don't already know how to program in this language. 

Pascal Language System User's Manual - This manual described booting the system and using 
each of the subsystems, such as the Editor, Compiler, and Assembler. 

Pascal Procedure Library User's Manual- This manual described using the libraries supplied with 
the system. The libraries consisted of I/O, graphics, LIF-ASCII Filer, Heap Management, and other 
procedures (etc. ) provided with the system. 

MC 68000 User's Manual - This manual described MC68000 processor hardware and instruction 
set. 

The Pascal Handbook - This manual described the Pascal language and extensions supported by 
the Series 200 Computers. 

Computers Supported by 1.0 

Pascal 1.0 supported only the 9826 and 9836, since they were the only Series 200 computers in 
production at the introduction of the Pascal 1.0 Workstation System. 
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Peripheral Devices Supported by 1.0 

Pascal 1.0 supported the following mass storage devices: 

• Internal 5.25-inch flexible disc drive 

• HP 9885 and 9895 8-inch Flexible Disc Drives 

• HP 9134 Hard Disc Drives 

Pascal 2.0 and 2.1 

Here are the additions to the 1.0 system and differences between the 2.1, 2.0, and 1.0 versions of 
the system. 

System Discs 

Pascal 2.0 and 2.1 Systems were distributed on six system discs, plus one documentation disc. 
Here are the names of the discs. 

BOOT: 

SYSV0L 

ACCESS 

CMPABM 

LIB: 

CONFIG: 

DOC: 

In contrast to the 1.0 file, the 2.x SYS VOL: LIBRARY was almost empty; the IO, GRAPHICS, and 
INTERFACE libraries were supplied on separate discs. The user could put just the ones he wanted 
into his System Library (usually the LIBRARY file). In addition, the Pascal 2.1 GRAPHICS library 
was re-structured internally and at the user-procedure level. 

The Initialization Library (BOOT:INITLIB) supplied contained device-driver software for the most 
common peripherals but not for all; this was done to conserve memory for the average user, since 
Pascal 2.x supported many more peripheral devices. The less commonly needed drivers were 
supplied on the separate CONFIG: disc. Thus, to configure a system to use certain peripherals, the 
Librarian needed to be used to install the required driver software in INITLIB. Documentation was 
provided which explained how and when to add optional modules to the INITLIB file. 

Documentation 

Documentation for the 2.0 system consisted of the five manuals supplied with the 1.0 system, plus 
the additional System Internals Documentation set. This set consisted of these three manuals: 

Pascal 2.0 System Designer's Guide - This manual described much of the inner workings of the 
Pascal system. It contained enough detail to allow you to use many of the "kernel" modules, and it 
also provided a fairly detailed description of Boot ROM contents and internal computer (hardware 
and software) architecture. 

Pascal 2.0 Source Code Listings (Volume I) - This manual consisted of a cross reference of Pascal 
procedure names used in the system, and listings of Assembler language modules in the system. 

Pascal 2.0 Source Code Listings (Volume II) - This manual consisted of the listings of many Pascal 
modules used in the system. 
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File System 

HP's Logical Interchange Format (LIF) directory structure was made the primary disc organization 
for 2.0 and later versions. (LIF ASCII files are intended for interchangability with other HP pro- 
ducts.) The 1.0 file system was only able to cleanly handle UCSD directory organizations. HP 
provided a library of routines to access LIF discs, but they were not integrated into the File System. 

The LIF library is not present in the 2.0 and later versions, since it is no longer necessary. The Lfiler 
(LIF Filer) is also unnecessary and has gone away, since the standard system Filer can now do the 
job. The 2.0 and later Filers are completely revised programs, although their behaviors are as 
similar as possible to the 1.0 Filer. 

If you were using the 1.0 version and are switching to a later release, don't panic! This does not 
mean that Pascal 1.0 discs are inaccessible, or even that you need to convert them. See the Special 
Configurations section of the Technical Reference Appendix for details. 

The 2.0 and later File Systems are completely reorganized in comparison to the 1.0 File System. 
The File System is now broken into levels called File Support (FS), Directory Access Method 
(DAM), Access Method (AM), and Transfer Method (TM). This organization allows the system to 
handle any number of different directory formats, and separates out the processing of each type of 
file structure which is supported. In fact, a customer can invent a new directory format or file type 
and bind it into the system so it can be used by all programs. 

The Directory Access Methods now supported are as follows: 

• HP Logical Interchange Format (LIF) 

• Shared Resource Manager hierarchical "structured" format (SDF) 

• UCSD-compatible (same format as Pascal 1.0) 

All these directory organizations are available through normal Pascal file operations. Files generated 
under Pascal 1.0 are all still fully usable. However, the newer systems can generate files and discs 
which cannot be properly interpreted by the 1.0 File System. 

System File Names 

The names of system files were changed with the 2.0 system. They were changed because their 
length was longer than allowed by the LIF directory format. The name changes are as follows: 

Old 1.0 File Name New Name 

SYSTEM. LINKER LIBRARIAN 

SYSTEM. EDITOR EDITOR 

SYSTEM. FILER FILER 

SYSTEM. COMPILER COMPILER 

SYSTEM. ASSMBLER ASSEMBLER 

SYSTEM. LIBRARY LIBRARY 

SYSTEM. TABLE TABLE 

SYSTEM. INITLIB INITLIB 

SYSTEM. MISCINF0 MISCINF0 

SYSTEM. STARTUP STARTUP 



Technical Reference 361 



Object Code Compatibility 

Several internal File System changes were made with Pascal 2.0. These changes resulted in 
corresponding changes in the internal representation of object code files. In general, when a version 
of the system is not compatible with other versions, the leading digit of the version number will be 
changed. For instance, versions 2.0 and 1.0 are not object-code compatible, while versions 2. 1 and 
2.0 are. 

While it is regrettable, there really is no alternative to these compatibility restrictions. On the positive 
side, Pascal application programs which don't "fiddle around" in the operating system are forward 
compatible to 2.x, so recompilation is all that's necessary. 

Supervisor Vs. User State 

In versions 2.0 and later, user programs run in the 68000' s "user" privilege mode, using the user 
stack pointer (USP). Interrupts run in "supervisor" privilege mode, using the system stack pointer 
(SSP). This has implications for calling Boot ROM routines, etc. See the MC60000 User's Manual 
for further details regarding these states. 

Additional Computer Supported by 2.0 

• Model 16 (HP 9816) 

Additional Computer Supported by 2.1 

• Model 20 (HP 9920) 

Peripheral Configuration 

The Pascal 2.x BOOT: TABLE auto-configuration program scanned interfaces for various peripher- 
als and automatically assigned File System unit numbers to devices found (if possible). That was a 
considerable improvement over the 1.0 version of TABLE. 

A source-code version (CTABLE.TEXT) was provided with the system. You could look at the 
program and read the corresponding commentary in the Special Configurations section of the 
Technical Reference Appendix to see exactly how the auto-configuration program works. You 
could also modify certain portions of it to make your own special configurations. 

Additional Peripherals Supported by 2.0 

Here are changes to the list of disc peripherals supported by Pascal 2.0. 

• The CS/80 discs (7908 family) 

• The Shared Resource Management system 

• The HP 8920x 5.25-inch Flexible Disc Drives 

• The HP 9121 3.5-inch (Single-Sided) Flexible Disc Drives 

• Several new versions of the HP 913x Hard Disc Drives (they appear as one large volume 
instead of four smaller ones) 

• Certain less obvious features were also added. For instance, the 2.0 system could be fairly 
easily configured to run from a terminal instead of the built-in CRT and keyboard. 
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Miscellaneous 

Up to 65 Kbytes of Global space has been made available with 2.0 and later versions. This change 
involved a redefinition of the use of register A5, which now points to an address 32 Kbytes below 
the start of Globals rather than above the first global variable. Consequently, routines in the Boot 
ROM cannot any longer be called directly; a small interfacing routine is now required to set up the 
registers and fool the TRY-RECOVER mechanism when calling Boot ROM routines. 

Pascal 3.0 

Here are the differences and additional features provided by the 3.0 version of the system. 

System Discs 

The Pascal 3.0 System is distributed on 8 discs, plus two for documentation. Here are the names of 
the discs. 

BOOT: 

SYSUOL: 

ACCESS: 

CMPi 

ASM: 

LIB; 

FLTLIB: 

CONFIG: 

DOC: 

DGLPRG: 

The BOOT:INITLIB file contains a more complete set of device-driver modules; for instance, it now 
contains module CS80 so that these discs will be recognized by the standard system. See the 
"Adding Modules to INITLIB" section of the "Special Configurations" chapter for a complete list of 
modules and descriptions of each. 

Note that the Assembler and Compiler were put on separate discs due to size. The CMP: disc 
contains the Compiler. The ASM: disc contains the DEBUGGER program (formerly in BOOT: INIT- 
LIB) and the new REVASM (reverse assembler) module. 

There are two versions of the GRAPHICS library. The FLTLIB: FGRAPHICS library contains 
modules optimized for using the HP 98635 Floating-Point Math card; they were compiled with the 
$FLOAT_HDW ON$ Compiler option, and use the 98635 card, if present. The LIB: GRAPHICS 
library uses routines in the REALS operating system module; these routines also access the Float- 
ing-Point Math card, if present, but the overhead in calling the routines decreases execution speed. 
The 98635 card can be used with all Pascal 3.0 programs, as long as the REALS module is installed 
(via INITLIB, etc.). 

The DGLPRG: disc provides magnetic copy of the example programs given in the new Pascal 3.0 
Graphics Techniques manual. 
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Documentation 

Here are the documents shipped with the Pascal 3.0 system. 

Pascal 3.0 User's Guide - This is a new manual that takes you from booting your system through 
setting up your "environment." It provides a "guided tour" of several subsystems, such as the 
Editor and Filer. You will see all of the steps required to enter, store, compile, and run a simple 
Pascal program. 

Problem Solving and Programming with Pascal - This is the textbook from which you can learn 
about Pascal programming, if you don't already know how to program in this language. 

Pascal 3.0 Workstation System - This manual describes in detail all of the subsystems, such as the 
Editor, Filer, and Compiler. It also describes such topics as how the computer configures itself to 
access File System peripherals and how to add new peripherals. This manual was formerly the 
Pascal 2.0 User's Manual. The "Getting Started" information (Chapter 1 of the former manual) has 
been moved to the new Pascal 3.0 User's Guide. Two new chapters have been added: Special 
Configurations and Non-Disc Mass Storage. 

Pascal 3.0 Procedure Library - This manual was formerly the Pascal Procedure Library User's 
Manual. It is basically the same as the former manual, except for the removal of the LIF Procedures 
and Graphics chapters (graphics is now covered in its own separate manual), and the addition of 
the System Devices and Segmentation Procedures chapters. 

Pascal 3.0 Graphics Techniques - This manual is an expanded version of the Graphics chapter of 
the former Pascal Procedure Library User's Manual. It provides several useful techniques that you 
can use in writing Pascal graphics programs. 

HP Pascal Language Reference for Series 200 Computers - This manual describes the HP Stan- 
dard Pascal language, as well as the implementation dependencies of the Workstation Pascal 
language. 

MC 68000 User's Manual - This manual describes MC68000 processor hardware and instruction 
set. It is the same manual as shipped with the 2.x Pascal systems. It also covers the 68008 and 
68010 processors. 

System Devices Procedural Interface 

The procedural interface to "system devices" (such as the keyboard, clock, screen, etc.) has been 
modified. These changes will not affect the way the system looks at the level of standard HP Pascal 
procedures. However, if any of your programs use procedures below this uppermost level (such as 
procedures in an operating system module), then you may have to make some changes. See the 
System Devices chapter of the Pascal 3.0 Procedure Library for complete details. 
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Additional Computers and Hardware Features Supported by 3.0 

• Model 217 (HP 9817) 

• Model 237 (HP 9837) 

Both Model 217 and Model 237 have a new type of keyboard which requires Pascal 3.0. The 
keyboard model number is the HP 46020, which uses the HP Human-Interface Link (HP-HIL) to 
communicate with the computer. 

Pascal 3.0 also supports an optional, "mouse" input device, which can be connected to the 
computer through the HP Human Interface Link (HP-HIL). The driver (provided on the CONFIG: 
disc) supports using the mouse for cursor-move ment in put in bo th horizontal and vertical direc- 
tions; it also defines the buttons on the mouse as ( Return ) or (ENTER) and ( Select ) ( ( EXECUTE ) ) keys. 
You also can access the mouse from your own applications programs; see the System Devices 
chapter of the Pascal Procedure Library manual for details. 

Both Models 217 and 237 may also have processor boards with Memory-Management Unit 
(MMU) hardware; if so, the product numbers have 'U' suffixes (such as HP 9817U and 9837U). If 
the cache-memory feature is also present, then the MMU hardware increases the execution speed 
of programs (because the cache-memory feature is automatically enabled by Pascal 3.0). 

The Model 237 implements a new type of display hardware: a bit-mapped combined alpha/ 
graphics display with a raster size of 1024 by 768 pixels on a 19-inch diagonal CRT screen. 

Additional Peripherals Supported by 3.0 

• The new Command Set/'80 (CS80) discs, including the HP 7914, 7933, and 7935 Disc Drives 

• New stand-alone DC600 (CS80) Tape Drives; right now this category only includes the HP 
9144 Tape Drive 

• New Sub-Set/'80 (SS80) floppy discs; right now this category only includes the HP 9122 
3.5-inch Double-Sided Floppy discs 

• Several new versions of the 913x Hard Discs (V and XV suffix drives) 

Additional Cards Supported by 3.0 

Here are the new cards that are supported by Pascal 3.0 

• HP 98255 EPROM and HP 98253 EPROM Programmer cards, which can be used as mass 
storage devices (see the Non-Disc Mass Storage chapter of this manual for details) 

• HP 98259 Magnetic Bubble Memory cards, which can also be used as mass storage devices 
(see the Non-Disc Mass Storage chapter of this manual for details) 

• HP 98635 Hoating-Point Math card (see the description of the FLOAT_HDW Compiler option 
in the Compiler chapter for details) 

• HP 98257 1 -Megabyte Memory card, which features parity-checking hardware 

Peripheral Configuration 

How the system boots and auto-configures itself is fully discussed in the Special Configurations 
chapter. The Pascal 3.0 TABLE program has even more capabilities than the 2.x version: it 
automatically configures up to 3 floppy disc drives (dual or single) and at least the first hard disc in 
the system (up to 10 are potentially possible). 
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A source-code version of the 3.0 TABLE program (CONFIG:CTABLE.TEXT) is also provided with 
the 3.0 system. You can look at the program and read the corresponding commentary in the 
Special Configurations chapter to see exactly how the auto-configuration process works, and you 
can modify certain portions of it to make your own special configurations. A major change with the 
3.0 TABLE is that now you can "coalesce" logical volumes on hard discs without the need to 
modify and re-compile the TABLE source program. 

The TABLE program can now easily support printers with RS-232C interfaces by making one small 
change in the program and re-compiling. See the Special Configurations chapter of this manual for 
details. 

Object Code Compatibility 

Several internal changes were made with Pascal 3.0. These changes resulted in corresponding 
changes in the internal representation of object code files. In general, when a version of the system 
is not compatible with other versions, the leading digit of the version number will be changed. For 
instance, versions 3.0 and 2.0 are not object-code compatible, while versions 2.1 and 2.0 are. 

While it is regrettable, there really is no alternative to these compatibility restrictions. On the positive 
side, Pascal application programs which don't "fiddle around" in the operating system are source- 
code compatible with 3.0, so recompilation is usually all that's necessary. 

General System Features Added by 3.0 

Stream Files: Stream files on read-only devices are now allowed; adding the C * ] specifier to the 
stream file name allows this usage by disabling the prompt feature. This same mechanism also 
allows the use of a stream file called AUTOKEYS to provide "autostart" capabilities with read-only 
system volumes. See the description of the Stream command in the Overview chapter of this 
manual for details. 

Filer: The Filer can now perform a Translate operation to the CONSOLE: volume, with the ability 
to view the translated file one screen at a time. See the Filer chapter of this manual for details. 

Compiler: The following Compiler options were added. The WARN option allows you to disable 
warning messages. The FLT_HDW option allows you to specify one of three actions: ON specifies 
that the Compiler is to emit code that assumes a 98635 Floating-Point Math card is installed in the 
computer; TEST specifies that the emitted code is to test for the presence of the card; OFF specifies 
that emitted code always uses floating-point library routines. See the Compiler chapter of this 
manual for details. 

Assembler: The Assembler has been modified to allow use of the new op codes provided by the 
68010 processor (such as the MOVES and RTD instructions). 



366 Technical Reference 



Librarian: A special "edit" mode was added to the Librarian. It allows you to add modules to an 
existing library more easily. The Librarian can also unassemble the new instructions for the 680xx 
processors (such as the MOVES and RTD instructions). See the Librarian chapter of this manual for 
details. 

Debugger: These are the new commands that have been added to the Debugger: "X" format for 
reverse assembly; "R" format for displaying REAL numbers; "0" format and FO default format for 
octal numbers; added repeat counts on format specifiers; "!" input format for binary numbers; "%" 
input format for octal numbers; relational operators can now be used in expressions; DA and DG 
commands for DUMP ALPHA and DUMP GRAPHICS functions, and also the ability to use the 
corresponding keys; four more softkeys now available (10 total); five more breakpoints now 
available (9 total); PN and PX commands (PX is an alternate syntax for the existing P command); 
IF, ELSE, and END commands for conditional ex ecution of Debugger commands added; CALL 
command added; EC and ETC commands added; (PAUSE) key definition changed. See the Debug- 
ger chapter of this manual for details. 

Segmentation Procedures: Several procedures that add the capability of run-time program seg- 
mentation have been added to the system. See the Segmentation Procedures chapter of the Pascal 
3. Procedure Library manual for details. 

Pascal 3.01 

The purpose of this revision is to fix bugs in version 3.0 of the Pascal system. The 3.01 BOOT: and 
ASM: discs contain software which corrects the bugs. (Note that other discs have not been revised.) 



Note 

These revisions do nor add any features to the system; they only fix 
bugs in existing features. 

Documentation Changes 

Since the 3.01 software does not add any features to the system, you may replace references to the 
3.0 BOOT: and ASM: discs with references to the 3.01 discs. 

Disposition of 3.0 BOOT: and ASM: Discs 

If you have version 3.0 BOOT: and ASM: discs, replace them with the 3.01 discs. Do not use the 
old discs any longer. 

List of Bugs Fixed 

Here are the areas in which bugs have been fixed by the 3.01 revisions: 

• Flexible disc initialization on Model 226 and 236 Computers equipped with an HP-UX Mem- 
ory Management processor board and the 3.0 Boot ROM. 

• Softkeys and bus errors while using the Debugger. 

• Disassembly of shift and rotate instructions with the REVASM module. 

• Model 237 display driver module (CRTB). 

• Non-advancing characters on some foreign language keyboards. 
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Pascal 3.1 

The main purpose of this version of the system is to add support of Series 300 computers. It also 
adds support of a few new peripherals, as well as fixes miscellaneous system bugs discovered since 
the release of Pascal 3.01. 

New Computer Hardware Supported by 3.1 

New features of the Series 300 computers include the following: 

• Many choices of processor, display, and human interface boards: 

• Five new displays (including a separate, high-speed display controller) 

• Two new processors: MC68010, and MC68020 (with MC68881 math co-processor) 

• Battery-backed, real-time clock 

• RS-232C serial interface (similar to the 98644 serial interface) 

• 46020 HP-HIL keyboard (similar to keyboards used with Models 217 and 237, but diffe- 
rent from other Series 200 models) 

• Support of two new foreign keyboards (Swiss-German and Swiss French). 

For a more complete description of the Series 300 enhancements to Series 200 hardware, see the 
"Porting to Series 300" chapter of the Pascal Workstation System manual. 

New Peripherals Supported by 3.1 

The 3.1 DGL (Device-independent Graphics Library) provides support for the following new 
HP-HIL (Hewlett-Packard Human Interface Link) devices: 

• HP 46087 and 46088 Graphics Tablets ("absolute" graphics input devices) 

• HP 35723 TouchScreen (also an "absolute" input device), which attaches to HP 35731 and 
35741 Medium-Resolution, 12-inch monitors 

Object Code Compatibility 

Pascal 3.1 is generally object-code compatible with Pascal 3.0 and 3.01 programs; i.e., programs 
compiled on the 3.0 or 3.01 systems will generally run on the 3.1 system (with no re-compilation 
required). However, you should not use 3.0 or 3.01 libraries on the 3.1 system. See the "Porting to 
Series 300" chapter of this manual for further information on how to determine object-code 
compatibility. 

Backward compatibility (i.e., running 3.1-compiled programs on a 3.0 or 3.01 system) is not 
generally supported. This incompatibility is the result of new run-time support modules that were 
added for the increases in sizes of SET variables (see the description of new Compiler features 
below for details regarding the increase in SET size) as well as changes in the interface to the 
SYSDEVS operating system module. 

General System Features Added by 3.1 

In general, the new system features provided by Pascal 3. 1 are related to the support of the new 
Series 300 computer hardware, or to new HIL peripherals. Here is a brief list of the features, 
organized according to subsystem. 
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Compiler: The new COMPILE20 compiler generates MC68020 instructions, and with the FLOAT_ 
HDW Compiler option supports the use of the MC6888 1 floating-point co-processor. See the 
"Compiler" chapter of this manual for details. 

A larger SET variable size limit is supported (was 256 elements; is now 262 000 elements). The 
COMPILER was also modified to fully conform to the HP Pascal Standard (the new COMPILE20 
compiler also fully conforms): 

• Conformant arrays are now supported. 

• Passing elements of packed arrays or records as VAR parameters to procedures or functions is 
now disallowed (preceding Compiler versions allowed it, although the HP Pascal Language 
Reference showed it as disallowed). You must now use the $ALLOW_PACKED ON$ compiler 
option if you want to pass this type of parameter. 

• You cannot assign values to the index of a FOR loop within the loop (previous versions 
allowed it). 

See the HP Pascal Language Reference for details. 

Assembler: The Assembler was upgraded to assemble MC68020 and MC6888 1 instructions. It 
also supports a new operand syntax which is required to assemble these instructions. See "Instruc- 
tion Syntax" in the "Assembler" chapter of this manual. 

Librarian: The Librarian was upgraded to dis-assemble all MC68020 and MC68881 instructions. 

Debugger: The REVASM module was also upgraded to dis-assemble all MC68020 and MC6888 1 
instructions. Since the MC68020 processor has a 32-bit address bus, all addresses specified in the 
Debugger command line must contain all 32 bits if located in RAM space (see the subsequent 
"Physical Memory Map" section for details on RAM space bounds). 

Error numbers: ESCAPECODE values 30 (arcsin or arccos argument is greater than 1) and 31 
(illegal real number) have been added to report MC68881 floating-point math co-processor errors. 

IO Library: The 10 library has added two registers for the built-in 98644 RS-232C serial interface 
in Series 300 computers. They allow you to simulate the configuration switches of the built-in 
98626 serial interface of the Series 200 Models 216 and 217 computers. See the "RS-232 Serial 
Interface" chapter of the Pascal Procedure Library manual for details. 

SYSDEVS interface: This operating system interface module has been modified in the way that 
highlight characters (130, 131, and 134 thru 143) are displayed in "debugger windows." The 
variable debuihiihlisht indicates which highlight(s) should be applied to characters put in a 
debugger window using the d b p u t operation. The d b h i s h 1 operation is a no-op for Series 300 and 
HP 98700 displays. See the "System Devices" chapter of the Pascal Procedure Library manual for 
details. 

Graphics Library: Another version of the Device-independent Graphics Library (DGL) is provided 
with the system (FLT20:FGRAPH20). It utilizes the MC68020 processor and MC6888! co- 
processor. (The FGRAPHICS library utilizes the HP 98635 Floating-Point Math Card; the 
GRAPHICS library uses math libraries. ) 
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System Discs 

Two new discs have been added to the 3.1 set (single-sided media options), making a total of 14 
discs: 

• The B00T2: disc contains the drivers for the Series 300 displays and for the HP 98700 
Display Controller. (The BOOT: disc is provided for Series 200 displays and for the HP 98546 
Compatibility Video Card Set; see the "Porting to Series 300" chapter for details of using the 
Compatibility Card. ) 

• The CMP20: disc contains a compiler that generates object code for the Series 300 computers 
that feature an MC68020 processor. 

• The FLT20: disc contains a new version of the Device-independent Graphics Library (DGL); 
the file is named FGRAPH20. The set of procedures it provides is the same as the GRAPHICS 
and FGRAPHICS libraries, but this library contains code that utilizes the MC68020 processor 
and MC68881 co-processor (instead of the HP 98635 Floating-Point Math Card). 

The contents of the following 3.1 discs have changed slightly from their 3.0 counterparts: 

• The LIB: disc has only the IO library. 

• The CONFIG: disc has a new file containing the new DGL_ABS module (support for the new 
HP-HIL graphics tablets and TouchScreen, which are "absolute" input devices). 

The rest of the 3.1 discs contain the same files as the 3.0 and 3.01 systems: 

BOOT: 

SYSU0L: 

ACCESS: 

CMP: 

ASM: 

GRAPH: 

FLTLI5: 

DOC: 

DGLPRG: 

Furthermore, the Workstation Pascal System is now available on double-sided, double-density, 
3V2-inch, flexible micro-disc media. With this media option, only eight discs are shipped: 

Double-Sided Corresponding Single-Sided Disc(s) 
Disc 

BOOT: Same files as single-sided BOOT: disc. 

BOOT2: Same files as single-sided BOOT2: disc. 

SYSVOL: Contains files on single-sided SYSVOL: , LIB: , and GRAPH: discs. 

ACCESS: Contains files on single-sided ACCESS: and CONFIG: discs. 

CMP: Contains files on single-sided CMP: and CMP20: discs. 

ASM: Same files as single-sided ASM: disc. 

FLTLIB: Contains files on single-sided FLTLIB: and FLT20: discs. 

DOC: Contains files on single-sided DOC: and DGLPRG: discs. 
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Documentation 

Manuals for the MC68020 processor and MC68881 co-processor have been added to the docu- 
mentation set. 

Pascal User's Guide: This manual has been updated to parallel the structure of the new Series 
200/300 Peripheral Installation Guide, as well as to discuss adding new peripherals supported by 
the 3. 1 system. 

Workstation Pascal System: The "Compiler" chapter describes the new ALLOW JP AC KED 
option, as well as the addition to the FLOAT_HDW option. The "Assembler" chapter has been 
revised to describe the new addressing modes available with the MC68020 processor. Chapters 10 
through 17 were added to describe Pascal programming topics specific to the Workstation System. 
Chapter 20 describes the considerations you must take in porting existing Pascal programs for 
Series 200 computers to run on Series 300 computers. 

Pascal Procedure Library: The "RS-232C Serial Interface" chapter describes the new registers for 
the built-in 98644 serial interface in Series 300 computers. The "System Devices" chapter de- 
scribes the changes to the SYSDEVS interface. 

Pascal Graphics Techniques: The "Interactive Graphics" chapter describes the new HIL input 
devices (graphics tablets and TouchScreen). The "Color Graphics" chapter describes the use of the 
new color displays. The "Procedure Reference" section has been updated accordingly. 

HP Pascal Language Reference: The "Compiler Options" section of the "Workstation Imple- 
mentation" appendix describes the new ALLOW_PACKED option, as well as the addition to the 
FLOAT_HDW option. 

All Pascal manuals have new part numbers with this revision of the system. 
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File Interchange Between Pascal and BASIC 

You may wish to exchange data on file between the Pascal and BASIC environments. There are a 
few rules you should follow. 

• Pascal and BASIC treat LIF directories on flexible discs similarly. ASCII text files are intended 
to be used as the interchange mechanism. 

• It was mentioned earlier that Pascal compresses the suffix of user file names in order to 
effectively allow longer file names. BASIC doesn't know about compressed names, so the 
BASIC program needs to invert the compression algorithm. This inversion is very simple, and 
is described in the section of the File System chapter called Programming with Files. Essential- 
ly, Pascal chops off the dot and the suffix (such as .ASC), then appends the first letter of the 
suffix and enough trailing "_" characters to make a 10-character name. Thus "ABC.ASC" 
becomes "ABCA ", which is the name BASIC will see. 

• BASIC can't deal with more than one LIF directory on a hard disc; Pascal, unless told other- 
wise, wants to divide large hard discs into several volumes each with its own directory. Hard 
disc partitioning is described in the Special Configurations chapter. 

If a disc is initialized by BASIC, Pascal and BASIC will both see the disc as one very large volume. 
Pascal's preference to partition the disc is overridden by what BASIC actually did. 

If a disc is initialized by Pascal and partitioned into multiple volumes, BASIC will only see the first 
volume and will not be able to access any part of the disc beyond the first volume. Pascal will see all 
the volumes. 

See the Special Configurations chapter for information on forcing Pascal to treat a partitionable disc 
as a single volume. 
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Notes 
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Module Names Used by the Operating System 

Here are the names of modules that are present in the system as it is shipped from the factory. They 
are provided so that you will not name a module using any of these names, unless you definitely 
want to override the system module's function. 

Note that many of these module names do not show up in the system symbol table (for example, 
they may have been removed by linking). However, you should not use them, because HP 
reserves the right to use them in the future. 

A complete list of symbol names actually used in the system is provided on the DOC: disc in the file 
named SYMBOLS. 



A804XDVR 

A804XINIT 

ABORTJO 

ALLREALSTUFF 

ALPHAFLAG 

ALPHALIST 

AMIGO 

AMIGODVR 

AMIGOINIT 

ASC_AM 

ASM 

BAT 

BKGND 

BOOT 

BOOTDAMMODULE 

BUBBLE 

BUBBLES 

BUB_DVR 

CHECK_TFR 

CHECK_TIMER 

CHOOK 

CI 

CLOCK 

CMD 

CONVERT 

CONVERT_TEXT 

CRT 

CRTB 

CS80 

CS80DSR 

CS80DVR 

CS80INIT 

CS80_CHAN_INDEP_CLR 

CSAMIGO 



DATAXOMM 

DC-INITIALIZE 

DEBUGGER 

DELAY_TIMER 

DGL.ABS 

DGL^RAS 

DGL^VTEXT 

DGLJ\UTL 

DGL_CONFG_IN 

DGL_CONFG_OUT 

DGL_GEN 

DGLHPGL 

DGL_HPGLI 

DGLJBODY 

DGLINQ 

DGL_KNOB 

DGLLIB 

DGLPOLY 

DGL_RAS 

DGL_RASTER 

DGL-TOOLS 

DGL_TYPES 

DGL_VAR 

DGLVARS 

DISCHPIB 

DISCINTJNITIALIZE 

DISCJNTF 

DMA 

DMAJNITIALIZE 

DMA.STBSY 

DROPDMA 

DRVASM 

EDRIVER 

EPROMS 



ERRJNFO 

EVALGVR 

EXCP 

EXTDC 

EXTDLEDI 

EXTG_EG 

EXTH.EH 

F9885 

F9885DVR 

F9885INIT 

FGATOR 

FLTPTHDW 

FS 

GENERALO 

GENERAL_1 

GENERAL_2 

GENERAL_3 

GENERAL_4 

GETDMA 

GLE^RAS_OUT 

GLE_ASCLIP 

GLE^lSTEXT 

GLE^UTL 

GLE_FILE_IO 

GLE_GEN 

GLE_GENI 

GLE_HPGL_IN 

GLE_HPGLOUT 

GLE_HPIB_IO 

GLE_KNOB_IN 

GLE_RAS_OUT 

GLE_SCLIP 

GLE_SMARK 

GLE_STEXT 



GLE_STROKE 

GLE.TYPES 

GLE_UTLS 

GP 

GPIO 

GPIOJNITIALIZE 

GRAPHICSBASE 

GRAPHICSFLAG 

G_DOLLAR 

HPHIL 

HPIB 

HPIBJ) 

HPIB_1 

HPIB_2 

HPIB_3 

HPIBJNITIALIZE 

HPM 

HV50 

HV52 

INITBAT 

INITBKGND 

INITCRT 

INITKBD 

INITLOAD 

INITUNITS 

INIT_BKGND 

INIT_DC 

INIT_DISCINT 

INIT_DMA 

INIT_GPIO 

INIT_HPIB 

INIT_RS 

INIT_SRM 

INIT_TIMER 



374 Technical Reference 



INSTALL_UCSD_DAM 

INSTLIFDAM 

INST_EPROM 

INTDC 

IOCOMASM 

IODECLARATIONS 

IOLIBRARY_KERNEL 

ISR 

ITXFR 

KATA 

KBD 

KERNEL 

KEYS 

LAST 

LDR 

LIFMODULE 

LIF_DAM 

LOADER 



LOCKMODULE 

LOGEOT 

LOGINT 

M68KTYPE 

MATCHDEFEXT 

MFS 

MINI 

MISC 

MSYSFLAGS 

NONUSKBD1 

NONUSKBD2 

PRINTER 

PRINTSYMS 

PRTDVR 

RAND 

RANDOM 

REALS 



RELOCATE 

RESETX 

REVASM 

REVASM_MOD 

RND 

ROMAN 

RS 

RS232 

RSJNITIALIZE 

SEGMENTER 

SERIAL_0 

SERIAL_3 

SETUPSYS 

SRM 

SRMAMMODULE 

SRMDAMMODULE 

STACKFUDGE 



STBSY 

STCLR 

SWAP8 

SWAPK 

SYSDEVICES 

SYSDEVS 

SYSGLOBALS 

TAPEBUF 

TESTDMA 

TEXT_AM 

TIMED_OUT 

TIMEREXISTS 

UCSDMODULE 

UCSD^M 

UIO 

WAIT_TFR 

WS1.0-DAM 
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Physical Memory Map 

The first part of this section describes the physical hardware memory map of your Series 200/300 
computer with regard to ROM space, I/O space and RAM space. This section begins with an 
overview of the hardware memory layout, followed by a more detailed memory map of each major 
section of memory. 

Register addresses and descriptions are included for the internal I/O devices. 



Full 16 Megabyte Addressing Range 

There are 23 address lines (BA1..BA23) 
providing 16 megabyte addressing on 
WORD boundaries. For byte operations, 
two control lines BUDS (Buffered Upper 
Data Strobe) and BLDS (Buffered Lower 
Data Strobe) indicate whether the upper 
data byte (BD8 through BD15), the lower 
data byte (BDO through BD7), or both 
bytes are involved in the communication. 
Note: When BAO = 0, the high byte is 
requested. When BAO = 1, the lower byte 
is requested. 



FFFF FFFF, 



FF80 0000 
007F FFFF 



0040 0000 
003F FFFF 1 

0000 0000 




Note 

For a complete description of the HP Series 200 computers' physical 
memory maps, see the Pascal System Internals documentation. 



1 On machines with Memory Management Units, the upper limit of ROM address is $1FFFFF. 
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A Hypothetical RAM Configuration 

RAM is located in the top half of the 16 megabyte addressing range. The bank select switches on 
the boards must be set so that the boards are mapped contiguously from highest memory progres- 
sing down. Any 1M boards should be set to the highest memory addresses. Any 256K boards 
should be mapped in next. Any 64K boards are mapped below those. The 64K on the CPU board 
automatically maps into the first available address below the plug-in boards. 



FFFF FFFF 16 






RAM 


FF80 0000 







FFFF FFFF 1£ 


1M : 






FFFO 0000 16 




FFEF FFFF lf 


: 256K 






FFEC 0000 




FFEB FFFF 


: 256K ; 






FFE8 0000 




FFE7 FFFF 


64K 






FFE7 0000 




FFE6 FFFF 


64K 






FFE6 0000 




FFE5 FFFF 


64K-CPU 






FFE5 0000 



The 1M memory boards have a 4-bit, user-changeable, bank-select switch. The 4 bits of the switch 
correspond to the 4 MSBs of the address bus. For example, the 1M board above has its switches set 
as follows: 

Msb Lsb 
1111 

The 256K memory boards have a 6-bit, user-changeable, bank-select switch. The 6 bits of the 
switch correspond to the 6 MSBs of the address bus. For example, the two 256K boards above 
have their switches set: 

Msb Lsb 

111011 
111010 



respectively. 
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After all the 256K memory boards have been set in high memory, the 64K boards should then be 
mapped in. It is necessary to set 8 switches, corresponding to the 8 MSBs of the address bus. For 
example two 64K boards mapped under the 256K boards above would have their switches set: 

Msb Lsb 

11100111 
11100110 

respectively. The 64K on the CPU board automatically maps into the first available memory space 
down: 

Msb Lsb 

11100101 



Note 

If the memory boards are not mapped contiguously, the auto-locating 
memory on the CPU board, if any, maps into the first hole left by the 
memory boards, and those mapped below the hole are not used. 



Note 

Setting the switches on two memory boards to the same code could 
cause damage to the memory boards. 



The Overall ROM Memory Map 



003F FFFF 16 










ROM 






• OPERATING 
SYSTEMS 


/ 
/ 
/ 
/ 
/ 
/ 
/ 
/ 
/ 


UNUSED 




• LANGUAGE 
EXTENSIONS 


/ 

/ 
/ 
/ 

/ 
/ 
/ 
/ 






•BOOT PROGRAM 
• SYSTEM ROUTINES 
•EXCEPTION VECTORS 


0000 0000 





0001 FFFF 16 



0000 4000 
0000 3FFF 

0000 0000 



The boot program, exception vectors, and some system routines reside on ROM chips starting at 
$000000 and extending to $003FFF. The space between $004000 and $01FFFF is unused. (The 
BOOTROM 3.0 consists of approximately 48 Kbytes of code, starting at $000000). The boot 
program checks for system ROMs and language extension ROMs on 16K boundries beginning at 
$020000 and continuing up to $3FC000. These ROMs are recognized by their appropriate header 
information. 
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Memory Mapped I/O 

I/O memory space is divided into three sec- 
tions. External I/O is that section which cor- 
responds to the backplane of the Series 
200/300 computers. The select codes on 
the backplane I/O cards correspond to 
address bits BA16 through BA20. 



007F FFFF 16 



0060 0000 
005F FFFF 



0050 0000 
004F FFFF 



0040 0000 



EXTERNAL 
I/O 



INTERNAL 

ASYNCHRONOUS 

I/O 



INTERNAL 

SYNCHRONOUS 

I/O 



External I/O 

All I/O cards available for the Series 200/ 
300 computers are mapped into the exter- 
nal I/O space on 64K boundaries (except 
the DMA card which maps with synchro- 
nous internal I/O). There are 32 such spaces 
between $600000 and $7FFFFF. User de- 
signed cards must also map into one of 
these spaces. The select codes correspond 
to address lines BA16 through BA20. HP 
cards have been assigned default select 
codes but can be reset by the user to map 
into any configuration. 



007F FFFF, 6 



007F 0000 
007E FFFF 



007E 0000 
007D FFFF 



0062 0000 
0061 FFFF 

0061 0000 
0060 FFFF 



0060 0000 



SELECT CODE 31 



SELECT CODE 30 



SELECT CODE 1 



SELECT CODE 



Internal I/O 
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005F FFFF 16 
0054 0000 


: RESERVED : 


0053 FFFF 
0053 0000 


GRAPHICS 


0052 FFFF 
0052 0000 


RESERVED 


0051 FFFF 
0051 0000 


CRT-ALPHA 


0050 FFFF 
0050 0000 


DMA 



004F FFFF, 6 
0048 0000 


RESERVED : 


0047 FFFF 
0047 0000 


STD. HP-IB 


0046 FFFF 
0046 0000 


RESERVED 


0045 FFFF 
0045 0000 


BATTERY 
BACKUP 


0044 FFFF 
0044 0000 


INTERNAL DISC 


0043 FFFF 
0043 0000 


RESERVED 


0042 FFFF 
0042 0000 


KEYBOARD 


0041 FFFF 
0040 0000 


RESERVED 



Synchronous 



Asynchronous 



Internal I/O functions are doubly mapped, once between $400000 and $4FFFFF, and again 
between $500000 and $5FFFFF. That is why much of the internal I/O space is reserved. Those 
I/O functions can be addressed in either range. The difference is that the low range generates a 
DTACK (Data Acknowledge) automatically, whether the card has actually responded to the 
data or not. If the synchronous cards are addressed in the high range, there will be no DTACK 
generated at all. 
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Notes 
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The Software Memory Map 

This software memory map shows the symbolic locations of global variables, local variables, the 
stack, the heap and the code relocation base. 

If you'll look at the directory of the boot 
disk, you'll see the files that are loaded 
into RAM at power-up. SYSTEM is loaded 
first. It shows as SYSTEM CODE on the 
map. It sets up the EXCEPTION 
VECTORS, MISCelaneous DATA, 
SYSTEM GLOBALS, SYSTEM STACK, 
INITLIB GLOBALS and SYSTEM HEAP. 
TABLE is loaded and it modifies some of 
the data in SYSTEM GLOBALS and 
SYSTEM HEAP. 

INITLIB is then loaded. It contains the I/O 
drivers and the Debugger. 

Finally, STARTUP is loaded. When you 
receive a Pascal Language System from 
HP, STARTUP is the Main Command 
Level command interpreter. It handles 
P-loading files, loading subsystem files, 
and loading user programs. You may use 
the Filer to change any file you want to 
STARTUP and that file will execute at 
power-up. A copy of the BOOT disc 
should be created before the change is 
made because you won't be able to 
change the file back to the original 
configuration. 



High RAM 


EXECPTION VECTORS 




MISC. DATA 




SYSTEM CODE 




SYSTEM STACK 


A5 — 


SYSTEM GLOBALS 




INITLIB GLOBALS 




COMMAND INTERPRETER GLOBALS 


Gbase(A5) — 


P-LOADED GLOBALS 


USER PROGRAM GLOBALS 


A6 — - 


USER PROGRAM STACK 


SP —- 
Sysglobals-14(A5)-» 


I 

MEMAVAIL 
(UCSD extension function) 

t 


USER PROGRAM HEAP 


Rbase — 


USER PROGRAM CODE 


P-LOADED CODE 




COMMAND INT.HEAP 




COMMAND INT. CODE 




INITLIB HEAP 




INITLIB CODE 


Low RAM 


SYSTEM HEAP 



Note 

For a complete description of the HP Series 200 Workstation Pascal's 
software memory map, see the Pascal System Internals documentation. 
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Character Sets 



This section provides tables for the following charater sets: 

• U.S. ASCII character set 

• U.S./European display characters (for Models 216, 220, 226, and 236 Computers) 

• U.S./European display characters (for Models 217 and 237 Computers) 

• U.S./European display characters (for all Series 300 Computers) 

• Katakana display characters (for all Series 200 Computers) 

• Monochrome highlight characters 

• Color highlight characters 
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U.S. ASCII Character Set 



ASCII 
Char. 


EQUIVALENT FORMS 


HP-IB 


Dec 


Binary 


Oct 


Hex 


NUL 





00000000 


000 


00 




SOH 


1 


00000001 


001 


01 


GTL 


STX 


2 


00000010 


002 


02 




ETX 


3 


0000001 1 


003 


03 




EOT 


4 


00000100 


004 


04 


SDC 


ENQ 


5 


00000101 


005 


05 


PPC 


ACK 


6 


00000110 


006 


06 




BEL 


7 


00000111 


007 


07 




BS 


8 


00001000 


010 


08 


GET 


HT 


9 


00001001 


011 


09 


TCT 


LF 


10 


00001010 


012 


0A 




VT 


11 


00001011 


013 


0B 




FF 


12 


00001100 


014 


OC 




CR 


13 


00001101 


015 


OD 




SO 


14 


00001110 


016 


OE 




SI 


15 


00001 1 1 1 


017 


OF 




DLE 


16 


00010000 


020 


10 




DC1 


17 


00010001 


021 


11 


LLO 


DC2 


18 


00010010 


022 


12 




DC3 


19 


00010011 


023 


13 




DC4 


20 


00010100 


024 


14 


DCL 


NAK 


21 


00010101 


025 


15 


PPU 


SYNC 


22 


00010110 


026 


16 




ETB 


23 


00010111 


027 


17 




CAN 


24 


00011000 


030 


18 


SPE 


EM 


25 


00011001 


031 


19 


SPD 


SUB 


26 


00011010 


032 


1A 




ESC 


27 


00011011 


033 


1B 




FS 


28 


00011100 


034 


1C 




GS 


29 


00011101 


035 


1D 




RS 


30 


00011110 


036 


1E 




US 


31 


0001 1111 


037 


1F 





ASCII 
Char. 


EQUIVALENT FORMS 


HP-IB 


Dec 


Binary 


Oct 


Hex 


space 


32 


00100000 


040 


20 


LAO 


! 


33 


00100001 


041 


21 


LA1 


" 


34 


00100010 


042 


22 


LA2 


# 


35 


00100011 


043 


23 


LA3 


$ 


36 


00100100 


044 


24 


LA4 


% 


37 


00100101 


045 


25 


LA5 


& 


38 


00100110 


046 


26 


LA6 


' 


39 


00100111 


047 


27 


LA7 


( 


40 


00101000 


050 


28 


LA8 


) 


41 


00101001 


051 


29 


LA9 


* 


42 


00101010 


052 


2A 


LA10 


+ 


43 


00101011 


053 


2B 


LA11 


» 


44 


00101100 


054 


2C 


LA12 


- 


45 


00101101 


055 


2D 


LA13 




46 


00101110 


056 


2E 


LA14 


/ 


47 


00101111 


057 


2F 


LA15 





48 


00110000 


060 


30 


LA16 


1 


49 


00110001 


061 


31 


LA17 


2 


50 


00110010 


062 


32 


LA18 


3 


51 


00110011 


063 


33 


LA19 


4 


52 


00110100 


064 


34 


LA20 


5 


53 


00110101 


065 


35 


LA21 


6 


54 


00110110 


066 


36 


LA22 


7 


55 


00110111 


067 


37 


LA23 


8 


56 


00111000 


070 


38 


LA24 


9 


57 


00111001 


071 


39 


LA25 




58 


00111010 


072 


3A 


LA26 


) 


59 


00111011 


073 


3B 


LA27 


< 


60 


00111100 


074 


3C 


LA28 


= 


61 


00111101 


075 


3D 


LA29 


> 


62 


00111110 


076 


3E 


LA30 


? 


63 


001 1 1 1 1 1 


077 


3F 


UNL 
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U.S. ASCII Character Set 



ASCII 


EQUIVALENT FORMS 


HP-IB 


Char. 


Dec 


Binary 


Oct 


Hex 


@ 


64 


01000000 


100 


40 


TAO 


A 


65 


01000001 


101 


41 


TA1 


B 


66 


01000010 


102 


42 


TA2 


C 


67 


01000011 


103 


43 


TA3 


D 


68 


01000100 


104 


44 


TA4 


E 


69 


01000101 


105 


45 


TA5 


F 


70 


01000110 


106 


46 


TA6 


G 


71 


01000111 


107 


47 


TA7 


H 


72 


01001000 


110 


48 


TA8 


' 


73 


01001001 


111 


49 


TA9 


J 


74 


01001010 


112 


4A 


TA10 


K 


75 


01001011 


113 


4B 


TA11 


L 


76 


01001100 


114 


4C 


TA12 


M 


77 


01001101 


115 


4D 


TA13 


N 


78 


01001110 


116 


4E 


TA14 





79 


01001111 


117 


4F 


TA15 


P 


80 


01010000 


120 


50 


TA16 


Q 


81 


01010001 


121 


51 


TA17 


R 


82 


01010010 


122 


52 


TA18 


S 


83 


01010011 


123 


53 


TA19 


T 


84 


01010100 


124 


54 


TA20 


U 


85 


01010101 


125 


55 


TA21 


V 


86 


01010110 


126 


56 


TA22 


w 


87 


01010111 


127 


57 


TA23 


X 


88 


01011000 


130 


58 


TA24 


Y 


89 


01011001 


131 


59 


TA25 


z 


90 


01011010 


132 


5A 


TA26 


[ 


91 


01011011 


133 


5B 


TA27 


\ 


92 


01011100 


134 


5C 


TA28 


] 


93 


01011101 


135 


5D 


TA29 


- 


94 


01011110 


136 


5E 


TA30 


— 


95 


01011111 


137 


5F 


UNT 



ASCII 
Char. 


EQUIVALENT FORMS 


HP-IB 


Dec 


Binary 


Oct 


Hex 


- 


96 


01100000 


140 


60 


SCO 


a 


97 


01100001 


141 


61 


SC1 


b 


98 


01100010 


142 


62 


SC2 


c 


99 


01100011 


143 


63 


SC3 


d 


100 


01100100 


144 


64 


SC4 


e 


101 


01100101 


145 


65 


SC5 


f 


102 


01100110 


146 


66 


SC6 


9 


103 


01100111 


147 


67 


SC7 


h 


104 


01101000 


150 


68 


SC8 


i 


105 


01101001 


151 


69 


SC9 


J 


106 


01101010 


152 


6A 


SC10 


k 


107 


01101011 


153 


6B 


SC11 


I 


108 


01101100 


154 


6C 


SC12 


m 


109 


01101101 


155 


6D 


SC13 


n 


110 


01101110 


156 


6E 


SC14 





111 


01101111 


157 


6F 


SC15 


P 


112 


01110000 


160 


70 


SC16 


q 


113 


01110001 


161 


71 


SC17 


r 


114 


01110010 


162 


72 


SC18 


s 


115 


01110011 


163 


73 


SC19 


t 


116 


01110100 


164 


74 


SC20 


u 


117 


01110101 


165 


75 


SC21 


V 


118 


01110110 


166 


76 


SC22 


w 


119 


01110111 


167 


77 


SC23 


X 


120 


01111000 


170 


78 


SC24 


y 


121 


01111001 


171 


79 


SC25 


z 


122 


01111010 


172 


7A 


SC26 


{ 


123 


01111011 


173 


7B 


SC27 


I 


124 


01111100 


174 


7C 


SC28 


} 


125 


01111101 


175 


7D 


SC29 


- 


126 


01111110 


176 


7E 


SC30 


DEL 


127 


01111111 


177 


7F 


SC31 
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U.S./European Display Characters 

These characters can be displayed on the alpha screens of Models 216, 220, 226, and 236 
Computers. 



ASCII 

Char. 


EQUIVALENT FORMS 


Dec 


Binary 


N 





00000000 


* 


1 


00000001 


:=, 


2 


00000010 


E, 


3 


00000011 


Er 


4 


00000100 


5j 


5 


00000101 


H 
K 


6 


00000110 


u 


7 


000001 1 1 


E i" 


8 


00001000 


H 

T 


9 


00001001 


If 


10 


00001010 


T 


11 


00001011 


if 


12 


00001100 


t: 


13 


00001101 


^;i 


14 


00001110 


; I 


15 


00001 1 1 1 


D 


16 


00010000 


\ 


17 


00010001 


IX 


18 


00010010 


h 


19 


00010011 


l * 


20 


00010100 


r-i 

K 


21 


00010101 


~r 


22 


00010110 


% 


23 


00010111 


'h 


24 


00011000 


6. 


25 


00011001 


% 


26 


00011010 


e; : 


27 


00011011 


% 


28 


00011100 


i> 


29 


00011101 


Er 


30 


00011110 


* 


31 


0001 1111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 




32 


00100000 


I 


33 


00100001 


II 


34 


00100010 


# 


35 


00100011 


* 


36 


00100100 


v. 


37 


00100101 


%: 


38 


00100110 




39 


00100111 


(. 


40 


00101000 


j 


41 


00101001 


•'£• 


42 


00101010 


+ 


43 


00101011 


!. 


44 


00101100 


... 


45 


00101101 


■■ 


46 


00101110 




47 


00101111 





48 


00110000 


1 


49 


00110001 


2 


50 


00110010 


■-. 


51 


00110011 


4 


52 


00110100 




53 


00110101 


€ 


54 


00110110 


7 


55 


00110111 


<-> 


56 


00111000 


9 


57 


00111001 


: 


58 


00111010 


H 


59 


00111011 




60 


00111100 


:= 


61 


00111101 




62 


00111110 


v 


63 


00111111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


@ 


64 


01000000 


hi 


65 


01000001 


E 


66 


01000010 


c 


67 


01000011 


D 


68 


01000100 


E 


69 


01000101 


F 


70 


01000110 


'.J 


71 


01000111 


H 


72 


01001000 


I 


73 


01001001 


.1 


74 


01001010 


K 


75 


01001011 


L 


76 


01001100 


M 


77 


01001101 


H 


78 


01001110 





79 


01001111 


p 


80 


01010000 


Q 


81 


01010001 


R 


82 


01010010 


s 


83 


01010011 


T 


84 


01010100 


1.1 


85 


01010101 


l tl l 


86 


01010110 


u 


87 


01010111 


' :: ' 


88 


01011000 


Y 


89 


01011001 


7 


90 


01011010 


L 


91 


01011011 




92 


01011100 


] 


93 


01011101 




94 


01011110 


..„ 


95 


01011111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 




96 


01100000 


•d. 


97 


01100001 


b 


98 


01100010 


r 


99 


01100011 


d 


100 


01100100 


e 


101 


01100101 


f 


102 


01100110 


g 


103 


01100111 


h 


104 


01101000 


1 


105 


01101001 


1 


106 


01101010 


k 


107 


01101011 


1 

I 


108 


01101100 


rn 


109 


01101101 


[""! 


110 


01101110 





111 


01101111 


p 


112 


01110000 


q 


113 


01110001 




114 


01110010 


s 


115 


01110011 


t 


116 


01110100 


u 


117 


01110101 


1. .! 


118 


01110110 


i,i 


119 


01110111 


X 


120 


01111000 


i,.J 


121 


01111001 


T 


122 


01111010 


i 


123 


01111011 


! 


124 


01111100 




125 


01111101 




126 


01111110 




127 


01111111 
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U.S./European Display Characters 

These characters can be displayed on the alpha screens of Models 216, 220, 226, and 236 
Computers. 



ASCII 


EQUIVALENT FORMS 




ASCII 
Char. 


EQUIVALENT FORMS 




ASCII 
Char. 


EQUIVALENT FORMS 




ASCII 


EQUIVALENT FORMS 


Char. 


Dec 


Binary 


Dec 


Binary 


Dec 


Binary 


Char. 


Dec 


Binary 


NOTE 


128 


10000000 




•F- 


160 


10100000 




•3 


192 


11000000 




>v 


224 


11100000 


NOTE 


129 


10000001 




r f 


161 


10100001 




!=' 


193 


11000001 




k 


225 


11100001 


NOTE 


130 


10000010 




'Y 


162 


10100010 




o 


194 


11000010 




h- 


226 


11100010 


NOTE 


131 


10000011 




k 


163 


10100011 




'_■! 


195 


11000011 




k 


227 


11100011 


NOTE 


132 


10000100 




h 


164 


10100100 




■EL 


196 


11000100 




h- 


228 


11100100 


NOTE 


133 


10000101 




h- 


165 


10100101 




I~' 


197 


11000101 




h- 


229 


11100101 


NOTE 


134 


10000110 




h- 


166 


10100110 




o 


198 


11000110 




h- 


230 


11100110 


NOTE 


135 


10000111 




h- 


167 


10100111 




u 


199 


11000111 




h- 


231 


11100111 


NOTE 


136 


10001000 






168 


10101000 




■3 


200 


11001000 




"> 


232 


11101000 


NOTE 


137 


10001001 






169 


10101001 




p 


201 


11001001 




^F- 


233 


11101001 


NOTE 


138 


10001010 






170 


10101010 




o 


202 


11001010 




' r f 


234 


11101010 


NOTE 


139 


10001011 






171 


10101011 




u 


203 


11001011 




h- 


235 


11101011 


NOTE 


140 


10001100 






172 


10101100 




•3 


204 


11001100 




>r 


236 


11101100 


NOTE 


141 


10001101 




h- 


173 


10101101 




l=* 


205 


11001101 




¥ 


237 


11101101 


NOTE 


142 


10001110 




h- 


174 


10101110 




Q 


206 


11001110 




! > 


238 


11101110 


NOTE 


143 


10001111 




£ 


175 


10101111 




u 


207 


11001111 




^f 


239 


11101111 


l t 


144 


10010000 






176 


10110000 




fl 


208 


11010000 




k 


240 


11110000 


h- 


145 


10010001 




^F- 


177 


10110001 




1 


209 


11010001 




k 


241 


11110001 


h- 


146 


10010010 




V 


178 


10110010 




s 


210 


11010010 




h- 


242 


11110010 


h- 


147 


10010011 




o 


179 


10110011 




I 


211 


11010011 




h- 


243 


11110011 


h- 


148 


10010100 




*F 


180 


10110100 




a. 


212 


11010100 




h- 


244 


11110100 


^P 


149 


10010101 




c 


181 


10110101 




1 


213 


11010101 




h- 


245 


11110101 


h- 


150 


10010110 




H 


182 


10110110 




e 


214 


11010110 




h- 


246 


11110110 


h- 


151 


10010111 




Pi 


183 


10110111 




* 


215 


11010111 




h- 


247 


11110111 


'f 


152 


10011000 




i 


184 


10111000 




fl 


216 


11011000 




h- 


248 


11111000 


' r f 


153 


10011001 




c 


185 


10111001 




i' 


217 


11011001 




h- 


249 


11111001 


! ! :- 


154 


10011010 




i'j 


186 


10111010 







218 


11011010 




k 


250 


11111010 


h- 


155 


10011011 




£ 


187 


10111011 




!J 


219 


11011011 




k 


251 


11111011 


h- 


156 


10011100 






188 


10111100 




E 


220 


11011100 




V 


252 


11111100 


V 


157 


10011101 




s 


189 


10111101 




i 


221 


11011101 




>> 


253 


11111101 


•f- 


158 


10011110 




k 


190 


10111110 




I.. 1 


222 


11011110 




k 


254 


11111110 




159 


10011111 




h- 


191 


10111111 




h- 


223 


11011111 




B 


255 


11111111 



NOTE: Ignored by the 9826; see "Monochrome Highlight Characters." 
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U.S./European Display Characters 

These characters can be displayed on the alpha screen of the Model 217 computer and on the 
bit-mapped graphics screen of the Model 237 computer. 



ASCII 


[ 














NUM. 


Chr, 


Num. 


Chr. 


Num. 


Chr. 


Num. 


Chr 





N 
U 


32 




64 


9 


96 


\ 


1 


S 
H 


33 


• 


65 


A 


97 


a 


2 


S 


34 


■1 


66 


B 


98 


b 


3 


E 
X 


35 


# 


67 


C 


99 


c 


4 


% 


36 


$ 


68 


D 


100 


d 


5 


E 
Q 


37 


% 


69 


E 


101 


e 


6 


A 
K 


38 


& 


70 


F 


102 


f 


7 





39 


I 


71 


G 


103 


g 


8 


e 
s 


40 


( 


72 


H 


104 


h 


9 


H 

T 


41 


) 


73 


I 


105 


i 


10 


V 


42 


* 


74 


J 


106 


J 


11 


T 


43 


+ 


75 


K 


107 


k 


12 


f f 


44 


> 


76 


L 


108 


1 


13 


C 

R 


45 


- 


77 


M 


109 


m 


14 


S 



46 


, 


78 


N 


110 


n 


15 


I 
I 


47 


/ 


79 


O 


111 


o 


16 


1 


48 





80 


P 


112 


P 


17 


D 1 


49 


1 


81 


Q 


113 


q 


18 


1 


50 


2 


82 


R 


114 


r 


19 


s 


51 


3 


83 


S 


115 


s 


20 


D 4 


52 


4 


84 


T 


116 


t 


21 


N 
K 


53 


5 


85 


U 


117 


u 


22 


% 


54 


6 


86 


V 


118 


V 


23 


% 


55 


7 


87 


Vi 


119 


w 


24 


& 


56 


8 


88 


X 


120 


X 


25 


% 


57 


9 


89 


Y 


121 


y 


26 


% 


58 


: 


90 


Z 


122 


z 


27 


\ 


59 


i 


91 


[ 


123 


{ 


28 


F s 


60 


< 


92 


\ 


124 


1 


29 


1 


61 


- 


93 


] 


125 


} 


30 


1 


62 


> 


94 


A 


126 


- 


31 


U S 


63 


? 


95 




127 


• 
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U.S./Europcan Display Characters 

These characters can be displayed on the alpha screen of the Model 217 computer and on the 

bit-mapped graphics screen of the Model 237 computer. 

ASCII 

Num. Chr, Num. Chr. Num. Chr. Num. Chr, 

160 192 a 224 A 

161 A 193 6 225 A 

162 A 194 6 226 § 

163 E 195 Q 227 D 

164 E 196 a 228 d 

165 E 197 6 229 ± 

166 ± 198 6 230 ± 

167 I 199 a 231 6 

168 ' 200 a 232 6 

169 % 201 6 233 O 

170 " 202 6 234 5 

171 203 U 235 3 

172 ~ 204 a 236 § 

173 205 e 237 

174 206 6 238 Y 

175 £ 207 u 239 y 

176 " 208 A 240 J> 

177 B ! 209 1 241 p 

178 °2 210 242 

179 211 A 243 

180 £ 212 a 244 

181 g 213 i 245 

182 ft 214 246 

183 ft 215 £ 247 * 

184 i 216 A 248 \ 

185 I 217 1 249 * 

186 H 218 d 250 * 

187 £ 219 O 251 « 

188 V 220 E 252 ■ 

189 % 221 l 253 » 

190 / 222 254 ± 

191 C 223 O 255 B 



128 


c 

L 


129 


I 

M 


130 


B 
G 


131 


I 
B 


132 


U 
i. 


133 


I 


134 


B 


135 


i 


136 


Ul 
H 


137 


R 
D 


138 


Y 

E 


139 


G 
R 


140 


C 
Y 


141 


B 
U 


142 


M 
G 


143 


B 
K 


144 


9 
O 


145 


9 
1 


146 


9 

2 


147 


9 
3 


148 


9 

a 


149 


s 

5 


150 


9 
G 


151 


9 

7 


152 


9 
8 


153 


9 

a 


154 


9 
A 


155 


9 
B 


156 


9 
C 


157 


a 

D 


158 


9 

E 


159 


9 

F 
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U.S./European Display Characters 

These characters can be displayed on the screen of Series 300 computers. 



ASCII 














Num. 


Chr. 


Num. 


Chr. 


Num. 


Chr. 


Num. 


Chr 





N 
U 


32 




64 


9 


96 


\ 


1 


* 


33 


i 


65 


A 


97 


a 


2 


s x 


34 


i< 


66 


B 


98 


b 


3 


e 

X 


35 


# 


67 


C 


99 


c 


4 


s 


36 


$ 


68 


D 


100 


d 


5 


E 
ft 


37 


% 


69 


E 


101 


e 


6 


n 


38 


& 


70 


F 


102 


f 


7 





39 


1 


71 


G 


103 


g 


8 


% 


40 


( 


72 


H 


104 


h 


9 


1 


41 


) 


73 


I 


105 


i 


10 


V 


42 


* 


74 


J 


106 


5 


11 


V T 


43 


+ 


75 


K 


107 


k 


12 


•f 


44 


i 


76 


L 


108 


1 


13 


C 

R 


45 


- 


77 


M 


109 


ro 


14 


S 



46 


. 


78 


N 


110 


n 


15 


s 
I 


47 


/ 


79 





111 


o 


16 




L 


48 





80 


P 


112 


P 


17 


°1 


49 


1 


81 


Q 


113 


q 


16 


1 


50 


2 


82 


R 


114 


r 


19 


S 


51 


3 


83 


S 


115 


s 


20 


°4 


52 


4 


84 


T 


116 


t 


21 


N 

K 


53 


5 


85 


U 


117 


u 


22 


% 


54 


6 


86 


V 


118 


V 


23 


% 


55 


7 


87 


W 


119 


w 


24 


% 


56 


8 


88 


X 


120 


X 


25 


% 


57 


9 


89 


Y 


121 


y 


26 


1 


58 


: 


90 


Z 


122 


z 


27 


* 


59 


> 


91 


[ 


123 


{ 


28 


\ 


60 


< 


92 


\ 


124 


1 


29 


% 


61 


m 


93 


] 


125 


} 


30 


I 


62 


> 


94 


sv 


126 


- 


31 


* 


63 


? 


95 




127 


i 
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U.S./European Display Characters 

These characters can be displayed on the screen of Series 300 computers. 



ASCII 

Num. Chr. Num. Chr. Num. Chr. Num. Chr. 

192 a 224 A 

193 & 225 A 

194 6 226 3 

195 Q 227 

196 a 228 (5 

197 6 229 ± 

198 6 230 ± 

199 ii 231 6 

200 a 232 lb 

201 6 233 

202 6 234 5 

203 il 235 S 

204 a 236 § 

205 e 237 

206 6 238 V 

207 u 239 y 

208 A 240 | 

209 I 241 p 

210 242 

211 A 243 JJ 

212 a 244 f 

213 1 245 : D 

214 a 246 

215 m 247 i 

216 A 248 £ 

217 1 249 * 

218 6 250 » 

219 251 « 

220 t 252 ■ 

221 i 253 » 

222 254 ± 

223 Q 255 Q 



128 


c 

L 


160 




129 


I 


161 


A 


130 


B 
G 


162 


A 


131 


I 

B 


163 


£ 


132 


U 

i. 


164 


e 


133 


I 


165 


E 


134 


B 


166 


± 


135 


I 


167 


I 


136 


u 

H 


168 


* 


137 


R 
D 


169 


** 


138 


Y 

E 


170 


*■ 


139 


G 
R 


171 




140 


C 
Y 


172 


"** 


141 


B 
U 


173 





142 


M 
G 


174 





143 


B 
K 


175 


€ 


144 


S 



176 




145 


s 

1 


177 


Y 


146 


s 

2 


178 


y 


147 


9 

3 


179 


" 


148 


9 

a 


180 


C 


149 


s 

5 


181 


? 


150 


9 
6 


182 


fl 


151 


9 

7 


183 


ft 


152 


9 
8 


184 


i 


153 


3 
9 


185 


i 


154 


e 

A 


186 


H 


155 


9 
B 


187 


£ 


156 


9 

C 


188 


V 


157 


a 




189 


\ 


158 


9 

E 


190 


i 


159 


9 

F 


191 


c 
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Katakana Display Characters 



These characters can be displayed on all Series 200 Computers (while in Katakana mode). 



ASCII 
Char. 


EQUIVALENT FORMS 




ASCII 

Char. 


EQUIVALENT FORMS 




ASCII 
Char. 


EQUIVALENT FORMS 




ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


Dec 


Binary 


Dec 


Binary 


Dec 


Binary 


I;4, 





00000000 




32 


00100000 


id 


64 


01000000 




96 


01100000 


\i 


1 


00000001 




I 


33 


00100001 




H 


65 


01000001 




a. 


97 


01100001 


\ 


2 


00000010 




'■'■ 


34 


00100010 




T> 


66 


01000010 




!■■■. 


98 


01100010 


E, 


3 


0000001 1 




it 


35 


00100011 






67 


01000011 






99 


01100011 


r 

■"!■ 


4 


00000100 




$ 


36 


00100100 




:d 


68 


01000100 






100 


01100100 


5j 


5 


00000101 




"■; 


37 


00100101 




i" 


69 


01000101 




e 


101 


01100101 


,: i- 


6 


00000110 




;:;, 


38 


00100110 




F 


70 


01000110 




f 


102 


01100110 


il 


7 


000001 1 1 






39 


00100111 




G 


71 


01000111 




q 


103 


01100111 


% 


8 


00001000 






40 


00101000 




h 


72 


01001000 




!•"! 


104 


01101000 


H 


9 


00001001 




> 


41 


00101001 




I 


73 


01001001 






105 


01101001 


If 


10 


00001010 




~h 


42 


00101010 






74 


01001010 




■J 


106 


01101010 


"t 


11 


00001011 




..,. 


43 


00101011 




l< 


75 


01001011 




i . 

K 


107 


01101011 


If 


12 


00001100 




? 


44 


00101100 






76 


01001100 




1 


108 


01101100 


F: 


13 


00001101 




... 


45 


00101101 




hi 


77 


01001101 






109 


01101101 


-M 


14 


00001110 




■ 


46 


00101110 




N 


78 


01001110 






110 


01101110 


: I 


15 


00001 1 1 1 






47 


00101111 




!"j 


79 


01001111 




o 


111 


01101111 


\ 


16 


00010000 







48 


00110000 




p 


80 


01010000 




p 


112 


01110000 


l-i 
"1 


17 


00010001 




"i 


49 


00110001 




Q 


81 


01010001 






113 


01110001 


i>. 


18 


00010010 




2 


50 


00110010 




R 


82 


01010010 




!" 


114 


01110010 


-j 


19 


00010011 




■"' 


51 


00110011 




s 


83 


01010011 






115 


01110011 


u :4 


20 


00010100 




4 


52 


00110100 




T 
! 


84 


01010100 




t. 


116 


01110100 


K 


21 


00010101 




5 


53 


00110101 




u 


85 


01010101 




j .1 


117 


01110101 


* 


22 


00010110 




rS 


54 


00110110 




J (J i 


86 


01010110 




!..; 


118 


01110110 


% 


23 


00010111 




i 


55 


00110111 




i,l 


87 


01010111 




i.ij 


119 


01110111 


V-i 


24 


00011000 




s 


56 


00111000 




■ :: ' 


88 


01011000 






120 


01111000 


\'-A 


25 


00011001 




! ™' 


57 


00111001 




Y 


89 


01011001 




:,.< 


121 


01111001 


k- 


26 


00011010 




' 


58 


00111010 






90 


01011010 




:;;:: 


122 


01111010 


£-■ 


27 


00011011 




; 


59 


00111011 






91 


01011011 






123 


01111011 


¥■:■ 


28 


00011100 






60 


00111100 




:.j.: 


92 


01011100 




j 


124 


01111100 


'■;'■ 


29 


00011101 




= 


61 


00111101 




] 


93 


01011101 






125 


01111101 


i:: - 


30 


00011110 






62 


00111110 






94 


01011110 






126 


01111110 


u- 


31 


0001 1111 




? 


63 


001 1 1 1 1 1 




— 


95 


01011111 






127 


01111111 
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Katakana Display Characters 



These characters can be displayed on all Series 200 Computers (while in Katakana mode). 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


NOTE 


128 


10000000 


NOTE 


129 


10000001 


NOTE 


130 


10000010 


NOTE 


131 


10000011 


NOTE 


132 


10000100 


NOTE 


133 


10000101 


NOTE 


134 


10000110 


NOTE 


135 


10000111 


NOTE 


136 


10001000 


NOTE 


137 


10001001 


NOTE 


138 


10001010 


NOTE 


139 


10001011 


NOTE 


140 


10001100 


NOTE 


141 


10001101 


NOTE 


142 


10001110 


NOTE 


143 


10001111 


NOTE 


144 


10010000 


NOTE 


145 


10010001 


NOTE 


146 


10010010 


NOTE 


147 


10010011 


NOTE 


148 


10010100 


NOTE 


149 


10010101 


NOTE 


150 


10010110 


NOTE 


151 


10010111 


NOTE 


152 


10011000 


NOTE 


153 


10011001 


NOTE 


154 


10011010 


NOTE 


155 


10011011 


NOTE 


156 


10011100 


NOTE 


157 


10011101 


NOTE 


158 


10011110 


NOTE 


159 


10011111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


h 


160 


10100000 


13 


161 


10100001 


r 


162 


10100010 


J 


163 


10100011 




164 


10100100 


■ 


165 


10100101 


"g 


166 


10100110 


y 


167 


10100111 


4 


16B 


10101000 


Hj 


169 


10101001 


:i: 


170 


10101010 


7f 


171 


10101011 


p 


172 


10101100 


., 


173 


10101101 


a 


174 


10101110 




175 


10101111 


... 


176 


10110000 


J 


177 


10110001 


■"■ 


178 


10110010 


,.,., 


179 


10110011 


I 


180 


10110100 


;f 


181 


10110101 


tl 


182 


10110110 


::|:: 


183 


10110111 


■•_■} 


184 


10111000 




185 


10111001 


J 


186 


10111010 


I? 


187 


10111011 


V 


188 


10111100 




189 


10111101 


+? 


190 


10111110 


■J 


191 


10111111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


•:? 


192 


11000000 


:f. 


193 


11000001 


M.I 


194 


11000010 


T 


195 


11000011 


[. 


196 


11000100 


+ 


197 


11000101 


- 


198 


11000110 


j? 


199 


11000111 


+ 


200 


11001000 


J 


201 


11001001 


i'l 


202 


11001010 


t 


203 


11001011 


-J 


204 


11001100 


•"•' 


205 


11001101 


ili 


206 


11001110 


T? 


207 


11001111 


=. 


208 


11010000 


u 


209 


11010001 


: . : ' 


210 


11010010 


T= 


211 


11010011 


■p 


212 


11010100 


.1 


213 


11010101 


3 


214 


11010110 


■■"i 


215 


11010111 


I.I 


216 


11011000 


ll 


217 


11011001 


L- 


218 


11011010 


D 


219 


11011011 




220 


11011100 


: -' 


221 


11011101 




222 


11011110 


U 


223 


11011111 



ASCII 
Char. 


EQUIVALENT FORMS 


Dec 


Binary 


j > 


224 


11100000 


¥ 


225 


11100001 


'? 


226 


11100010 


h- 


227 


11100011 


*t 


228 


11100100 


h 


229 


11100101 


h 


230 


11100110 


h- 


231 


11100111 


r 


232 


11101000 


! F- 


233 


11101001 


k 


234 


11101010 


k 


235 


11101011 


'!> 


236 


11101100 


r 


237 


11101101 


h- 


238 


11101110 


k 


239 


11101111 


h- 


240 


11110000 


h- 


241 


1111 0001 


h- 


242 


11110010 


T 


243 


11110011 


k 


244 


11110100 


\r. 


245 


11110101 


h- 


246 


11110110 


iv. 


247 


11110111 


Iv. 


248 


11111000 


h 


249 


11111001 


Ye. 

r 


250 


11111010 


i'f. 


251 


11111011 


r 


252 


1 1 1 1 1 1 00 


■f 


253 


11111101 




254 


11111110 


1 


255 


11111111 



NOTE: These are the same as the U.S./European characters. 
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Monochrome Highlight Characters 

These characters affect the highlight mode on all subsequently displayed characters on 
monochrome displays (not implemented on some Model 216 and 220 displays). Note that bit- 
mapped alpha displays have no blinking or half-bright modes (Model 237 and all Series 300 
displays). 



ASCII 

code 


halfbright 


underline 


blinking 


inverse 
video 


128 










129 








X 


130 






X 




131 






X 


X 


132 




X 






133 




X 




X 


134 




X 


X 




135 




X 


X 


X 


136 


X 








137 


X 






X 


138 


X 




X 




139 


X 




X 


X 


140 


X 


X 






141 


X 


X 




X 


142 


X 


X 


X 




143 


X 


X 


X 


X 



"X" means that this highlight is enabled by displaying the character. 

Color Highlight Characters 

These characters change the color of subsequently displayed characters on the alpha screen of 
color displays. 



ASCII 




code 


Resultant Color 


136 


white (pen 1) 


137 


red (pen 2) 


138 


yellow (pen 3) 


139 


green (pen 4) 


140 


cyan (pen 5) 


141 


blue (pen 6) 


142 


magenta (pen 7) 


143 


black (pen 0) 



Note that the colors shown in this table are the default colors for the corresponding pen number. 
On Series 300 displays, changing one of these pen colors also affects the color corresponding to the 
character. However, on the Model 236C, changing one of these pen colors has no effect on the 
alpha display character's color. 
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Command Summaries 



Main Command Level Summary 



Assembler-Run the Assembler. 
Compiler-Run the Pascal Compiler. 
Debugger-Run the Debugger subsystem 
Editor-Run the Editor subsystem. 
eXecute-Execute a specified object file. 
Filer-Run the Filer subsystem. 
Initialize-Places all current blocked devices online. 
Librarian-Run the Librarian subsystem. 
Memvol-Create a memory resident volume. 
Newsys-Select a new System Volume. 



Permanent-Move an object file from a mass stor- 
age medium into internal read/write memory. 

Run-Compile and execute the workfile or execute 
the last file compiled. 

Stream-Stream a text file to be processed as 
keyboard commands. 

User restart-Run the last program executed. 

Version-Display version information about the Pas- 
cal Operating System. 

What-Display the complete file specifier of each 
Pascal subsystem. 

?-Display alternate command prompt. 
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Editor Command Summary 



Text Modifying Commands 

Copy - Insert text from the copy buffer or an 
external file in front of the current cursor 
location. 

Delete - Remove text from the current cursor 
locatio n to the loca tion of the cursor when 
( Select ) ( ( EXECUTE 1 ) is pressed. 

Insert - Inserts text in front of the current cursor 
location. 

Replace - Replace the specified target string 
with the specified substitute string. 

eXchange - Replace the text at the cursor with 

text typed from the keyboard, on a 
character-by-character basis. 

Zap - Delete all text between the anchor and 
the current cursor location. (The anchor is set 
at the location of the latest Adjust, Find, Insert, 
or Replace command. ) 

Text Formatting Commands 

Adjust - Adjust the column in which a line (or lines) 
start. 

Margin - Format the paragraph the cursor is lo- 
cated to the margins in the current environment. 

Miscellaneous Commands 

Quit - Leave the Editor in an orderly manner. Pro- 
vides various ways for saving the text currently in 
memory. 

( STOP ) ( (SHIF) - (cIfllJ) ) - terminates the Editor 
subsystem, but the text is lost. 

Set - Modify the environment or set markers in the 
text. 

Verify - Update the displayed text to reflect the text 
stored in memory. 



Curso r Keys 

( TAB ) - Move cursor to next tab position (fixed 
tabs) in the current direction. 



[Return] or (ENTER) - Move cursor in current direc- 
tion to the leftmost character in the next line. 

Space Bar - Move cursor one character in the 
current direction. 

Arrow Keys - Move cursor in the direction speci- 
fied by the key. 

Cursor Wheel - Move s the cursor like the arrow 
keys. Without ("SHIFT) , works like right and left 
arrows; with ( SHIFT) , works like the up and 
down arrows. 

Curso r Positioni ng Com mands 

( = ] — Typing ( = ) positions the cursor at 
the anchor. (The anchor is set at the location of 
the latest Adjust, Find, Insert, or Replace com- 
mand. ) 

Find - Position the cursor after the specified target 
string. 

Jump - Position the cursor at the beginning, the 
end, or the specified marker. 

Page - Position the cursor ± 23 lines from the 
current location. 
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Filer Command Summary 



Volume Related Commands 

Bad sectors - Scans a volume and searches for un- 
reliable (bad) storage areas. 

Extended Directory - Lists directory information 
about a specified volume or set of files. 

Krunch - Consolidates all unused space on a 
volume in a single area by packing the existing 
files together. (Not valid for SRM) 

List Directory - Lists directory information about a 
specified volume or set of files. 

Prefix - Specifies a new default volume. 

Volumes - Lists the volumes currently on line. 

Udir - Sets the default unit directory. (SRM only) 

Zero - Creates an empty directory on the specified 
volume. (Not valid for SRM) 

Exit Commands 

Quit - Provides an orderly exit from the filer. 



STOP - Pressing the ( STOP ) key unconditional- 
ly exits the Filer Subsystem. The current I/O 
operation is completed before exiting. 



File Related Commands 

Access - Change the access rights (passwords) on 
a file or directory. (SRM only) 

Change - Change the name of a file, set of files, or 
volume. 

Duplicate link - Duplicates links to a file or set of 
files. (SRM only) 

Filecopy - Copies a file, set of files, or a volume to 
a specified destination. 

Make - Create a directory (SRM) or a file on a 
volume. 

Remove - Remove a directory entry or a set of 
directory entries. 

Translate - Translates text files of types TEXT, 
ASCII, and DATA to other text file representations 
or to unblocked volumes. 

Workfile Related Commands 

Get - Specifies a file as the workfile. 

New - Specifies that no file is the current workfile. 

Save - Saves the current workfile(s) with the speci- 
fied name. 

What - Lists the name and current state (saved or 
not saved) of the workfile(s). 
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Librarian Command Summary 



General Commands 

Boot - creates "system Boot files." 

Edit - gets you into Edit mode, for either Copying 
or Linking. 

File - sends the File directory (all module names) to 
the current Printout file. 

Header - allows you to specify the Header size for 
the Output file. 

Input - allows you to specify the Input file. 

Keep - makes a permanent copy of the current 
Output file. 

Output - allows you to specify the Output file. 

Printout - turns the Printout option ON or OFF, or 
allows you to specify a Printout file. 

Quit - quits the Librarian and returns you to the 
Main Command Level. 

Unassemble — gets you into the Unassemble mode. 

Verify - gets you into the Verify mode, and shows 
the name of the first module in the Input. 

Copy Mode Commands 

All - transfers All modules from the Input file to the 
Output file. 

Link - gets you into Link mode. 

Module - allows you to specify the next Module to 
be copied from the Input file. 

Transfer - Transfers the current object module to 
the Output file. 

Edit Mode Commands 

Append - Appends modules to the Output file. 

Copy - Copies the First module up to (but not 
including) the Until module to the Output file. 

First - allows you to specify the First module to be 
transferred to the Output file. 

Stop - Stops the Edit session and returns to the 
Librarian's main prompt. 

Transfer - Transfers the current object module to 
the Output file. 

Until — allows you to specify the Until module. 



Link Mode Commands 

All - transfers All modules from the Input file to the 
Output file. 

Copy - returns you to Copy mode. 

Def - controls whether or not the DEF table is in- 
cluded in the Output file. 

Global - allows you to change the Global base 
address of the module. 

Link - finishes Linking. 

Module - allows you to specify the next Module to 
be copied from the Input file. 

New - allows you to name the New object module 
being created. 

Relocation - designate the Relocation base address 
to be used. 

Space - assigns Space for patches. 

Transfer — Transfers the current object module to 
the Output file. 

X - allows you to enter a copyright notice as part of 
the Output file. 

Unassemble Commands 

Assembler - directs the Librarian to unassemble 
the Input file using Assembler conventions. 

Compiler - unassembles all lines of the Input file 
according to Compiler conventions. 

Def - sends the DEF table to the Printout file. 

Ext - sends the EXT table to the Printout file. 

Line range - unassemble (using Compiler conven- 
tions) a section of code defined by two Line 
values. 

PC range - unassemble (using Assembler conven- 
tions) a section of code defined by two location 
counter range values. 

Stop - Stops the unassemble session and returns to 
the Librarian's main prompt. 

Text- sends the interface Text (DEFINE SOURCE) 
of the current Input module to the Printout file. 
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Debugger Command Summary 



Register Operations 

A0..A7, D0..D7, PC, SP, US, SR - Display or 
assign values to the processor registers. 

Breakpoint Commands 

BS - Set a breakpoint at the specified location. 

BD - Disable (but don't remove) breakpoints. 
BA - Activate disabled breakpoints. 
BC - Clear and remove breakpoints. 
B - Display the breakpoint table 

Call Command 

CALL - Calls the machine-language routine at the 
specified address. 

Display Command 

D - Display the specified object(s) immediately, 
directly, or indirectly. 

Dump Commands 

DA - Performs a DUMP ALPHA function. 

DG - Performs a DUMP ALPHA function. 

Escape Commands 

EC - Generates the specified escape code. 

ET - Specify escape codes to be trapped by the 
Debugger. 

ETC - Sets up trapping of all escape codes; the 
Debugger executes specified command(s) when 
an escape is encountered. 

ETN - Specify that all escape codes except the 
ones listed are to be trapped by the Debugger. 

Format Commands 

FB - Sets the default display format to Binary. 

FH - Sets default format to hex values. 

FI - Sets default format to signed integer values. 

FO - Sets the default display format to Octal. 

FU - Sets default format to unsigned integer 
values. 

Go Commands 

G — Resume execution. 

GT - Resume execution at a specified location. 

GTF or GFT - Same as GT except execution is 
slowed and the line numbers are flashed in the 
lower right corner of the CRT. 



IF, ELSE, and END Commands 
IF, ELSE, END - Allow conditional execution of 
Debugger command(s). 

Open Memory Commands 

OB, OW, OL - Display or alter memory locations. 

Procedure Commands 

PN - Continues the program, but halts program 
execution when the next procedure is called (or 
current one is exited, whichever occurs first). 

PX, or P - Continues the program, but halts pro- 
gram execution when the current procedure is ex- 
ited. 

Queue Commands 

Q - List the most recent line numbers (or PC values 
if Trace commands were used with machine 
code). 

QE - Terminate recording of line number values in 
the queue. 

QS - Start recording the information in the queue. 

Softke y Comm ands 

( l<0 ) ... f l<9 ) - Define softkeys as typing-aid 
keys. 

System Boot Command 

sb - The system boot command puts the computer 
in the power-up state for rebooting. 

Trace Commands 

T - Execute the specified number of instructions, 
each followed by a TD command. 

TD - Dis play th e command string defined by the 
softkey [ k4 ) . 

T D I - Restores the initial command string to 

CKD- 

TQ - Same as the T command except the TD 
command is executed only after the last in- 
struction. 

TT - Same as the TQ command except a loca- 
tion is specified rather than a count. 

Walk Procedure Links Commands 

WD - Move the stack frame pointer to the stack 
frame of the calling procedure. 

WS - Move the stack frame pointer to the stack 
frame of the nesting procedure. 

WR - Return the stack frame pointer to the current 
stack frame. 



400 Command Summaries 



Notes 



401 




ASCII character Any of the 8-bit characters in Hewlett-Packard's extended ASCII (American 
Standard Code for Information Interchange) set. The characters include letters, numerals, 
punctuation, control characters and foreign character sets. A table of these characters and their 
code values can be found in the "Character Sets" appendix. 

anchor An internal pointer used by the Editor's Zap command as a starting point for removing 
text. The anchor is set at the cursor position of the most recent Adjust, Find, Insert or Replace 
command. The cursor is moved to the anchor location by the Equals command. 

bit An abbreviation for the term "binary digit", a bit is a single digit in base 2 that must be either a 
Ooral. 

block A block is a 512-byte unit of storage area on a WS1.0 volume and a 256-byte sector on a 
LIF volume. The Pascal system allocates storage space for files on the WS1.0 and LIF volumes 
in block increments. 

block-structured An attribute of a device which structures its memory allocation in block units; 
examples are flexible or hard discs. Devices such as printers and screens (CRTs) are not 
block-structured. 

boot device The peripheral where the Boot ROM found and loaded the Pascal operating system. 
The Boot ROM has a search pattern which allows booting from just about any drive in any HP 
mass storage product, including the Shared Resource Manager. 

bus address When several peripherals are connected to the same HP-IB interface, a bus address 
is required (in addition to the select code) to designate the particular peripheral referenced by 
an I/O transaction. 

byte A group of eight bits processed as a unit. 

control character Any ASCII character whose value is either 127 or in the range of thru 31. 
Use of control characters in the Editor and Filer is discouraged, because they may have 
undesirable effects. 

cursor The flashing underline (_) symbol on the screen. The cursor functions as a reference point 
for Editor commands which manipulate text and as a reference for prompts in other Pascal 
subsystems. 

cursor wheel The wheel (also called the knob) on the upper left area of the non-ITF ke yboard 
whose action duplicates that of the four arrow keys. When used in the Editor with the [ SHIFT ) 
key pressed, turning the wheel produces up or down cursor movement; unshifted, it pro- 
duces left or right cursor movement. 
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device selector By convention in the Pascal, BASIC and HPL systems, when select code and 
bus address are used together to address a peripheral, they are concatenated into a single 
number. Thus the device at address 1 on select code seven is referenced as 701, which is 
derived by multiplying the select code by 100 and adding the address. Some HP products 
contain, within a single package, several peripheral devices which must are addressed 
separately. 

directory Contains information about the files on a volume. This information includes the 
volume name and the following information about each file on the medium: the file name, 
the file size (in number of blocks), the date of last modification to the file, its starting block 
address, and the file type (which reflects the file's attributes). Directory information can be 
seen by using the Filer's List Directory and Extended Directory commands. The directory is 
initialized with the Filer's Zero command. 

Directory Access Method or DAM Each mass storage unit has a directory describing the files 
it contains, the type of each file and so forth. Many different directory organizations are used 
within HP, and data on a disc can't be interpreted properly unless it is accessed using the 
correct Directory Access Method. Pascal 2.0 and later versions support three DAMs: the 
"Workstation" format compatible with Pascal 1.0 systems; HP's "Logical Interchange For- 
mat" or LIF directory; and the Shared Resource Manager's hierarchical directory. 

dollar sign This character "$" is used in the Filer as a convenience in specifying file names. 
When used in place of a destination file name, it means that the file is to have the same 
name as the source file. 

entry point The place where a program or subroutine begins. Before a routine is executed, 
the address of the entry point must be obtained from a symbol table and that address is put 
in the program counter. 

environment The conditions or parameters which affect how text in the Editor is Adjusted, 
Inserted, and Margined. These parameters may be changed with the Editor's Set command. 

file A discrete collection of information designated by a file name and residing on a mass 
storage medium. 

file name An entry in a directory which identifies a particular file. 

file specification Completely identifies a file and may include both a volume specification 
and a file name. A volume specification can be one of many items, but it is always part of a 
file specification. If a volume ID is given, it must be separated from the file name by a colon 
(:). If not, the default volume is assumed. 
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file types Several file types are recognized by the Pascal System. Files generally (but not 
always) have a suffix as part of the file name which indicates their type. The file type is 
established at the time of the file's creation and cannot be changed just by changing the 
suffix. The types and their associated suffixes are: 

• TEXT files - (suffix is .TEXT) Contain ASCII characters and Editor environment information. 

• ASCII files - (suffix is .ASC) Are similar to TEXT files. The format is slightly different and there 
is no Editor environment information. 

• CODE files - (suffix is .CODE) Contain code generated by the Pascal Assembler, Compiler or 
Librarian. 

• Data files - (no specific suffix) Are files which can be created by any subsystem but are used 
primarily as INPUT and OUPUT files in Pascal programs. They do not have suffixes. 

• System files - (suffix is .SYSTM) Are files created with the Librarian's Boot command. They are 
loadable by the boot ROM. 

• Bad files - (suffix is .BAD) are a type of file created by the user to isolate unreliable or worn-out 
areas on a mass storage medium. Once created, BAD files will not be moved by subsequent 
crunches of the volume. 

interface The electronic circuitry which connects the computer's high-speed internal bus to lower 
speed physical peripheral devices. Interfaces are either built-in, like the standard HP-IB port at 
the back of your computer, or plug into the I/O backplane. Most of the peripherals supported by 
the Series 200/300 computers are designed to connect through an HP-IB interface. 

knob The rotary-pulse generator that is used as an input device on the built-in keyboards of the 
9826 and 9836, on optional HP 98203B keyboards, and on the HP46083 HIL knob optional 
on computers with HIL keyboards. It is used in the Editor for moving the cursor (in that context, 
it is referred to as the ' 'cursor wheel' ' ). You can use it in programs for any purpose that you like. 

library A file that contains object modules. Libraries are the object of the compiler, Assembler, or 
Librarian. 

Librarian A Pascal subsystem designed to manage object modules. It can link or just collect 
object modules together into object files. Th e Libra rian is the file named LIBRARIAN in the 
operating system and is accessed by pressing ( L ) from the Main Command Level. 

LIBRARY A special library included with the Pascal operating system. This file is usually 
designated as the System Library at power-up. (The System Library is a special library file 
automatically accessed by the compiler and loader.) The System file should be kept on-line 
so that object modules stored in it are automatically available to any program importing 
them. 

Main Command Level The level from which all the subsystems of the Pascal System are 
entered. The prompt displayed at this level looks like: 

Command: Compiler Editor Filer Initialize Librarian Run eXeoute Version ? 
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module See "object module". 

mouse A small, rodent-like input device, consisting of a roller ball and buttons. Rolling the 
device on any surface generates two-dimensional movement information that is transmitted 
through its tail to the computer. Pushing the buttons also generates information that is sent 
to the computer. The mice available with Series 200/300 equipment are connected to the 
computer through the HP Human-Interface Link (HP-HIL). 

object file An object file is a unit of binary code managed by the Librarian. It is made up of a 
Library directory and one or more object modules. The Assembler and Compiler generate 
one object file per source file. The Compiler's object file can contain one or more object 
modules depending upon the source file's construction. If the source file contains a number 
of compilable modules, that number of object modules will be created in the object file. 

object module Contains the interface information necessary to link and run the module and 
the machine code. 

on-line Any object (device, volume or file) currently accessible by the Pascal System. 

opcode A word that stands for one of the operations of the microprocessor. The Assembler 
translates these words into actual binary codes which the microprocessor understands. 

operand The symbol which stands for the object on which microprocessor operations are 
performed. 

Pascal module HP Pascal allows program modules to be compiled separately into object 
modules. The modules are generally not executable, but are parts of Pascal programs. The 
sections of a module are: 

MODULE* EXPORT* IMPORT* IMPLEMENT 

pass by reference The address of a parameter variable is given to the called routine. Using 
that address, the routine can alter the value of the variable. 

pass by value The current value of a variable is given to the called routine. In this way the 
value can be used but the routine does not alter the actual variable. 

peripheral An I/O device such as a printer or disc. 

prompt Generally, any request for information from the system. The different Pascal subsys- 
tems have primary prompts (the Editor Prompt, Filer Prompt, etc. ) and many subsystem 
commands have prompts of their own which are displayed at the top of the screen when the 
command is entered. 
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pterodactyl A large flying reptile, presumed extinct. 

relative addressing An addressing mode where the location of a routine or variable is given 
as an offset from the current location rather than an absolute address. In this way, the code 
can be placed at different places in memory without having to change the addresses of 
variables and entry points. 

select code A number between and 31, the "address" or name by which an interface is 
identified and referenced. When a peripheral operation is performed, it takes place through 
an interface which is said to be "on a select code". Most interface cards which plug into the 
I/O backplane have switches which can be set to indicate the select code to which the 
interface will respond. The built-in interfaces have fixed select codes. 

string A contiguous series of non-control ASCII characters. 

structured constant A constant that has more than a single value, such as a record or array. 

structured variable A variable that has more than a single value, such as a record or array. 

symbol table A table containing the address locations of the variables and routine entry 
points. 

system volume or system unit The Pascal system distinguishes one mass storage unit to be 
used for special purposes. This "system volume" is where the date and any AUTOSTART 
(or AUTOKEYS) file are found at boot time. It is where the system looks first for system files 
such as the Compiler and Editor, where workfiles are stored, and where an intermediate file 
is stored during interpretation of a Stream (command) file. 

text file A file created and/or used by the Editor which contains ASCII or selected foreign 
characters. The Editor automatically appends . TEXT to a file name unless it either already 
contains a suffix or the last character in the file name is a period. A text file may be of type 
TEXT, ASCII or DATA. 

unit An entry in the Unit Table. 

Unit Table The Pascal system provides for up to 50 units, designated #1 through #50. They 
are represented by a 50-entry array called the Unit Table or "Unitable". Each entry fully 
specifies the association of one logical unit to a physical peripheral, with such information as 
the device selector and driver procedures to be used for I/O operations to the unit. 

unit number An integer in the range from 1 through 50 representing the volume having the 
corresponding entry in the unit table. 
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volume A volume refers to any I/O device such as a printer, keyboard, screen, or mass 
storage device. The name of a mass storage volume is found in its directory; the name of an 
unblocked device is found in its Unit Table entry. There may be several volumes on one 
physical storage medium. Hard discs typically contain multiple volumes, but flexible discs 
generally have only a single volume. The volume may be mounted (in a disc drive) or not. 
The syntax of a volume name depends on its type (for example, LIF volume names may 
contain 6 characters, WS1.0 may contain 7). 

wildcard Both of the characters = and ? can be used in the Filer as wildcards in place of parts 
of a file specification. 

workfile If the workfile exists, it is the automatic file used by the Editor, Compiler, Assembler, 
Debugger and the Run command. It is designated when quitting the Editor using the Update 
option or the Filer's Get command. 
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Error Messages 



This appendix contains all of the error messages and conditions that you are likely to encounter 
while using the Pascal system. They can be placed into the following categories; each category is 
discussed in a subsequent section. 

• Unreported errors - certain errors do not get reported by this implementation of Pascal. 

• Boot-time errors - These are errors that occur while the Pascal system is booting (they are 
reported by the system loader). 

• Run-time errors - These are general errors which may occur while you are using the system. 
Run-time errors — 10, - 26, and - 27 have special meanings, as described below. 

I/O System errors - When run-time error - 10 occurs, there has been a problem with the I/O 
system. The operating system then prints an error message from the list of I/O system errors. 

I/O Library errors - When run-time error - 26 occurs, there has been a problem in an 10 
library procedure. 

Graphics Library errors - When run-time error -27 occurs, there has been a problem in a 
GRAPHICS library procedure. 

• Compiler syntax errors. 

• Editor, Filer, and Debugger errors and conditions. 



Unreported Errors 

The following errors in Pascal programs are not reported by this implementation of the language. 

• Disposing a pointer while in the scope of a WITH referencing the variable to which it points. 

• Disposing a pointer while the variable it points to is being used as a VAR parameter. 

• Disposing an uninitialized or NIL pointer. 

• Disposing a pointer to a variant record using the wrong tagfield list. 

• Assignment to a FOR-loop control variable while inside the loop. 

• GOTO into a conditional or structured statement. 

• Exiting a function before a result value has been assigned. 

• Changing the tagfield of a dynamic variable to a value other than was specified in the call to 
NEW. 

• Accessing a variant field when the tagfield indicates a different variant. 

• Negative field width parameters in a WRITE statement. 

• The underscore character "_" is allowed in identifiers. This is permitted in HP Pascal, but is not 
reported as an error when compiling with $ ANS I $ specified. 

• Value range error is not always reported when an illegal value is assigned to a variable of type 
SET. 
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Boot-Time Errors 

Errors that occur while your system is booting will report a message like this: 

IORESULT. ERROR: 0, 112 

The value of IORESULT is shown first (0 in the above display). See the I/O System Errors section for 
descriptions of those error numbers. 

The value of ERROR is shown second (112 in the above display). See the Loader/SEGMENTER 
Errors section for a description of those error numbers. 



Run-Time Errors 

Errors detected by the operating system during the execution of a program generate one of the 
error messages listed on this page (unless you trap it with a TRY.. RECOVER construct). 



Note 

Note that error - 10 occurs, the error message listed here will not be 
shown; the message on the next page (in I/O System Errors) will be 
shown instead. 

When using a TRY.. RECOVER construct (which requires the $SYSPROG ON$ Compiler option), 
the following numbers correspond to the value returned by the ESCAPECODE function. 



Normal termination. 

1 Abnormal termination. 

2 Not enough memory. 

3 Reference to NIL pointer. 

4 Integer overflow. 

5 Divide by zero. 

6 Real math overflow. (The number was too 
large.) 

7 Real math underflow. (The number was too 
small. ) 

8 Value range error. 

9 Case value range error. 

10 Non-zero IORESULT. (Note that the cones- 
ponding message on the next page, not this 
message, will be shown. ) 

11 CPU word access to odd address. 

12 CPU bus error. 

13 Illegal CPU instruction. 

14 CPU privilege violation. 



- 15 Bad argument - SIN/COS. 

- 16 Bad argument - Natural Log. 

- 17 Bad argument - SQRT. (Square root.) 

- 18 Bad argument - real/BCD conversion. 
- 19 Bad argument - BCD/real conversion. 

- 20 Stopped by user. 

- 21 Unassigned CPU trap. 
-22 Reserved 

- 23 Reserved 

- 24 Macro Parameter not 0..9 or a..z. 

- 25 Undefined Macro parameter. 

- 26 Error in I/O subsystem. 

- 27 Graphics routine error. 

- 28 Parity error in memory. 

-29 Misc. floating-point hardware error. 
-30 Arcsin, arccos argument > 1. 
-31 Illegal real number. 
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I/O System Errors 

These error messages are automatically printed by the system unless you have enclosed the 
error-producing statement in a TRY.. RECOVER construct. Within the RECOVER block, the 
ESCAPECODE function returning a value of - 10 indicates that one of the following errors has 
occurred; you can determine which error has occurred by using the IORESULT function. 



No I/O error reported. 

1 Parity (CRC) incorrect. 

2 Illegal unit number. 

3 Illegal I/O request. 

4 Device timeout. 

5 Volume went off-line. 

6 File lost in directory. 

7 Bad file name. 

8 No room on volume. 

9 Volume not found. 

10 File not found. 

11 Duplicate directory entry. 

12 File already open. 

13 File not open. 

14 Bad input format. 

15 Disc block out of range. 

16 Device absent or unaccessible. 

17 Media initialization failed. 

18 Media is write protected. 

19 Unexpected interrupt. 

20 Hardware/media failure. 

21 Unrecognized error state. 

22 DMA absent or unavailable. 

23 File size not compatible with type. 

24 File not opened for reading. 

25 File not opened for writing. 

26 File not opened for direct access. 



27 No room in directory. 

28 String subscript out of range. 

29 Bad file close string parameter. 

30 Attempt to read or write past end-of-file mark. 

31 Media not initialized. 

32 Block not found. 

33 Device not ready or medium absent. 

34 Media absent. 

35 No directory on volume. 

36 File type illegal or does not match request. 

37 Parameter illegal or out of range. 

38 File cannot be extended. 

39 Undefined operation for file. 

40 File not lockable. 

41 File already locked. 

42 File not locked. 

43 Directory not empty. 

44 Too many files open on device. 

45 Access to file not allowed. 

46 Invalid password. 

47 File is not a directory. 

48 Operation not allowed on directory. 

49 Cannot create /WORKSTATIONS/TEMP_ 
FILES. 

50 Unrecognized SRM error. 

51 Medium may have been changed. 

52 IO result was 52. 



410 Error Messages 



I/O Library Errors 



When run-time error —26 occurs, there has been a problem in an I/O library procedure. 
By importing the IODECLARATIONS module, you can use the IOE_RESULT and 
IOERROR-MESSAGE functions to get a textual error description. For example: 

*SYSPR0G 0N$ 

♦ ♦ ♦ 

import IODECLARATIONS* GENERAL_3 5 

t ♦ ♦ 
be Sin 
try 

+ ♦ ♦ 
recover 

if ESCAPECODE = IOESCAPECODE 

then writeln ( IOERROR-MESSAGE < IOE_RESULT )) 5 
ESCAPE(ESCAPECODE) 5 
end . 

IOESCAPECODE is a constant (= -26) which you can import from the IODECLARATIONS 
module. ESCAPE is a procedure and ESCAPECODE is a function; both are accessible when you 
use the $SYSPROG ON$ Compiler option. 






No error. 


17 


1 


No card at select code. 


18 


2 


Interface should be HP-IB. 


19 


3 


Not active controller. 


20 


4 


Should be device address, 


21 




not select code. 


22 


5 


No space left in buffer. 


23 


6 


No data left in buffer. 


306 


7 


Improper transfer attempted. 


313 


8 


The select code is busy. 


314 


9 


The buffer is busy. 


315 


10 


Improper transfer count. 


316 


11 


Bad timeout value. 


317 


12 


No driver for this card. 


318 


13 


No DMA. 


319 


14 


Word operations not allowed. 


325 


15 


Not addressed as talker. 


326 


16 


Not addressed as listener. 


327 



A timeout has occurred. 

Not system controller. 

Bad status or control. 

Bad set/clear/test operations. 

Interface card is dead. 

End/eod has occurred. 

Miscellaneous - value of parameter error. 

Data-Comm interface failure. 

USART receive buffer overflow. 

Receive buffer overflow. 

Missing clock. 

CTS false too long. 

Lost carrier disconnect. 

No activity disconnect. 

Connection not established. 

Bad data bits/parity combination. 

Bad status/control register. 

Control value out of range. 
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Graphics Errors 

When run-time error -27 occurs, there has been an error in a GRAPHICS library routine. 

By importing the DGL_LIB module, you can call the GRAPHICSERROR function which returns an 
INTEGER value you can cross reference with the numbered list of graphics errors. 

$SYSPROG DN$ 

♦ ♦ ♦ 

import DGI LIB? 

♦ ♦ ♦ 
b e 3 i n 

t ry 

• ♦ ♦ 
recover 

if ESCAPECODE = -27 

then writeln ('Graphics error *'» GRAPHICSERROR* 

' has occurred') 
else ESCAPE(ESCAPECODE) 5 
end . 

You may wish to write a procedure which takes the INTEGER value from GRAPHICSERROR and 
prints the description of the error on the CRT. You could keep this procedure with your program or, 
for more global use, in the System Library (normally SYSVOL:LIBRARY). 

No error. {Since last call to GRAPHICSERROR or GRAPHICSJNIT.} 

1 The graphics system is not initialized. 

2 The graphics display is not enabled. 

3 The locator device is not enabled. 

4 ECHO value requires a graphic display to be enabled. 

5 The graphics system is already enabled. 

6 Illegal aspect ratio specified. 

7 Illegal parameters specified. 

8 The parameters specified are outside the physical display limits. 

9 The parameters specified are outside the limits of the window. 

10 The logical locator and the logical display use the same physical device. {The logical locator limits 
cannot be redefined explicitly. They must correspond to the logical view surface limits.} 

11 The parameters specified are outside the current virtual coordinate system boundary. 

12 The escape function requested is not supported by the graphics display device. 

13 The parameters specified are outside of the physical locator limits. 
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Loader/SEGMENTER Errors 

Here is a list of errors that can be generated by a program that uses the SEGMENTER module (or 
by the loader; see Boot-Time Errors): 



Error 


Meaning 


100.. 105 


field overflow trying to link or relocate something 


110 


circular or too deeply nested symbol definitions 


111 


improper link info format 


112 


not enough memory 


116 


file was not a code file 


117 


not enough space in the explicit global area 


118 


incorrect version number 


119 


unresolved external references 


120 


generated by the dummy procedure returned by fincLproc 


121 


unloacLsegment called when there are no more segments to unload 


122 


not enough space in the explicit code area 



SEGMENTER Errors 

When one of these errors occurs while using the SEGMENTER module procedures, you can 
determine which has occurred by using a TRY.. RECOVER construct and calling the 
ESCAPECODE function in the RECOVER block. 

Loader Boot-Time Errors 

When an error occurs while booting, a message such as the following will be reported: 



I0RESULT, ERROR 



112 



The second number indicates which loader error has occurred. (The first number indicates which 
I/O system error has occurred; see the preceding I/O System Errors section for descriptions of each 
error. ) 
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Pascal Compiler Errors 

The following errors may occur during the compilation of a HP Pascal program. 



ANSI/ISO Pascal Errors 

1 Erroneous declaration of simple type 

2 Expected an identifier 

4 Expected a right parenthesis ")" 

5 Expected a colon ":" 

6 Symbol is not valid in this context 

7 Error in parameter list 

8 Expected the keyword OF 

9 Expected a left parenthesis "(" 

10 Erroneous type declaration 

11 Expected a left bracket "[" 

12 Expected a right bracket "]" 

13 Expected the keyword END 

14 Expected a semicolon ";" 

15 Expected an integer 

16 Expected an equal sign " = " 

17 Expected the keyword BEGIN 

18 Expected a digit following "." 

19 Error in field list of a record declaration 

20 Expected a comma ",'' 

21 Expected a period "." 

22 Expected a range specification symbol ".. 

23 Expected an end of comment delimiter 

24 Expected a dollar sign "$" 

50 Error in constant specification 

51 Expected an assignment operator ": = " 

52 Expected the keyword THEN 

53 Expected the keyword UNTIL 

54 Expected the keyword DO 

55 Expected the keyword TO or DOWNTO 

56 Variable expected 

58 Erroneous factor in expression 

59 Erroneous symbol following a variable 



98 Illegal character in source text 

99 End of source text reached before end of pro- 
gram 

100 End of program reached before end of source 
text 

101 Identifier was already declared 

102 Low bound > high bound in range of con- 
stants 

103 Identifier is not of the appropriate class 

104 Identifier was not declared 

105 Non-numeric expressions cannot be signed 

106 Expected a numeric constant here 

107 Endpoint values of range must be compatible 
and ordinal 

108 NIL may not be redeclared 

110 Tagfield type in a variant record is not ordinal 

111 Variant case label is not compatible with tag- 
field 

113 Array dimension type is not ordinal 

115 Set base type is not ordinal 

117 An unsatisfied forward reference remains 

121 Pass by value parameter cannot be type FILE 

123 Type of function result is missing from declara- 
tion 

125 Erroneous type of argument for built-in 
routine 

126 Number of arguments different from number 
of formal parameters 

127 Argument is not compatible with correspond- 
ing parameter 

129 Operands in expression are not compatible 

130 Second operand of IN is not a set 

131 Only equality tests ( = , <> ) allowed on this 
type 

132 Tests for strict inclusion ( <, > ) not allowed 
on sets 
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133 Relational comparison not allowed on this 
type 

134 Operand(s) are not proper type for this opera- 
tion 

135 Expression does not evaluate to a boolean re- 
sult 

136 Set elements are not of ordinal type 

137 Set elements are not compatible with set base 
type 

138 Variable is not an ARRAY structure 

139 Array index is not compatible with declared 
subscript 

140 Variable is not a RECORD structure 

141 Variable is not a pointer or FILE structure 

143 FOR loop control variable is not of ordinal 
type 

144 CASE selector is not of ordinal type 

145 Limit values not compatible with loop control 
variable 

147 Case label is not compatible with selector 

149 Array dimension is not bounded 

150 Illegal to assign value to built-in function 
identifier 

152 No field of that name in the pertinent record 

154 Illegal argument to match pass by reference 
parameter 

156 Case label has already been used 

158 Structure is not a variant record 

160 Previous declaration was not forward 

163 Statement label not in range 0..9999 

164 Target of nonlocal GOTO not in outermost 
compound statement 

165 Statement label has already been used 

166 Statement label was already declared 

167 Statement label was not declared 

168 Undefined statement label 

169 Set base type is not bounded 

171 Parameter list conflicts with forward declara- 
tion 



177 Cannot assign value to function outside its 
body 

181 Function must contain assignment to function 
result 

182 Set element is not in range of set base type 

183 File has illegal element type 

184 File parameter must be of type TEXT 

185 Undeclared external file or no file parameter 

190 Attempt to use type identifier in its own dec- 
laration 

300 Division by zero 

301 Overflow in constant expression 

302 Index expression out of bounds 

303 Value out of range 

304 Element expression out of range 

400 Unable to open list file 

401 File or volume not found 

403.. Compiler error 
409 

Compiler options 

600 Directive is not at beginning of the program 

601 Indentation too large for SPAGEWIDTH 

602 Directive not valid in executable code 

604 Too many parameters to $SEARCH 

605 Conditional compilation directives out of order 

606 Feature not in Standard PASCAL flagged by 
$ANSI ON 

607 Feature only allowed when $UCSD enabled 

608 $INCLUDE exceeds maximum allowed depth 
of files 

609 Cannot access this $INCLUDE file 

610 $INCLUDE or IMPORT nesting too deep to 
IMPORT <module-name> 

611 Error in accessing library file 

612 Language extension not enabled 

613 Imported module does not have interface text 

614 LINENUM must be in the range 0. . 65535 
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620 Only first instance of routine may have 
$ALIAS 

621 $ALIAS not in procedure or function header 

646 Directive not allowed in EXPORT section 

647 Illegal file name 

648 Illegal operand in compiler directive 

649 Unrecognized compiler directive 

Implementation restrictions 

651 Reference to a standard routine that is not im- 
plemented 

652 Illegal assignment or CALL involving a stan- 
dard procedure 

653 Routine cannot be followed by 
CONST, TYPE, VAR, or MODULE 

655 Record or array constructor not allowed in ex- 
ecutable statement 

657 Loop control variable must be local variable 

658 Sets are restricted to the ordinal range .. 
261 999 

659 Cannot blank pad literal to more than 255 
characters 

660 String constant cannot extend past text line 

661 Integer constant exceeds the range im- 
plemented 

662 Nesting level of identifier scopes exceeds max- 
imum (20) 

663 Nesting level of declared routines exceeds 
maximum (15) 

665 CASE statement must contain a non- 
OTHERWISE clause 

667 Routine was already declared forward 

668 Forward routine may not be external 

671 Procedure too long 

672 Structure is too large to be allocated 

673 File component size must be in range 
1..32766 

674 Field in record constructor improper or missing 

675 Array element too large 

676 Structured constant has been discarded (cf. 
$SAVE_CONST) 



677 Constant overflow 

678 Allowable string length is 1..255 characters 

679 Range of case labels too large 

680 Real constant has too many digits 

681 Real number not allowed 

682 Error in structured constant 

683 More than 32767 bytes of data 

684 Expression too complex 

685 Variable in READ or WRITE list exceeds 
32767 bytes 

686 Field width parameter must be in range 0. . 255 

687 Cannot IMPORT module name in its EXPORT 
section 

688 Structured constant not allowed in FOR- 
WARD module 

689 Module name may not exceed 15 characters 

696 Array elements are not packed 

697 Array lower bound is too large 

698 File parameter required 

699 32-bit arithmetic overflow 

Non-ISO Language Features 

701 Cannot dereference ( A ) variable of type 
anyptr 

702 Cannot make an assignment to this type of 
variable 

704 Illegal use of module name 

705 Too many concrete modules 

706 Concrete or external instance required 

707 Variable is of type not allowed in variant re- 
cords 

708 Integer following # is greater than 255 

709 Illegal character in a "sharp" string 

710 Illegal item in EXPORT section 

711 Expected the keyword IMPLEMENT 

712 Expected the keyword RECOVER 

714 Expected the keyword EXPORT 

715 Expected the keyword MODULE 
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716 Structured constant has erroneous type 

717 Illegal item in IMPORT section 

718 CALL to other than a procedural variable 

719 Module already implemented (duplicate con- 
crete module) 

720 Concrete module not allowed here 

730 Structured constant component incompatible 
with corresponding type 

731 Array constant has incorrect number of ele- 
ments 

732 Length specification required 

733 Type identifier required 

750 Error in constant expression 

751 Function result type must be assignable 

900 Insufficient space to open code file 

901 Insufficient space to open ref file 

902 Insufficient space to open def file 

903 Error in opening code file 

904 Error in opening ref file 

905 Error in opening def file 

906 Code file full 

907 Ref file full 

908 Def file full 
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Assembler Errors 

Error messages are listed under the line in which they occur. At the completion of the assembly, the 
number of errors will be displayed. If there are errors, there will be a directive for you to check the 
location of the last error in the program. At that location there will be a description of the error. Also 
listed will be the location of the error above it if one exists. In this manner, all errors can be located 
without having to search the whole listing. 

Error Messages 

Address Register Expected. 

Attempt to Nest Included Files. 

Blank or EOL Expected. 

Comma Expected. 

Code Segment Starts at Odd Address. 

Duplicate Definition of Symbol. 

Error Reading Code File. 

Error Reading Source File. 

Error Writing Code File. 

Error Writing Source File. 

Error Reading Code File. 

Expression is Improper Mode. 

External Reference Not Allowed. 

Failed to Open Included File. File could not be found. 

Field Overflow. A specification of the assembly instruction will not fit within the appropriate field 
of the machine instruction. 

Illegal Constant. 

Illegal Expression. 

Illegal Operand Size for this Instruction. 

Illegal Syntax. 

Improper Addressing Mode 

Improper Use of Mode Declaration. Symbol already has mode or declaration appears after first 

use of symbol. 
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Improper Use of Size Suffix. 

Invalid Opcode. 

Label Required. For some pseudo-ops. 

Module Directory Overflow. Too many ORG or RORG statements in assembly or Non- 
Contiguous DS statements. 

More Than One COM Statement. 

More Than One MNAME Statement. 

More Than One START Statement. 

Phase Error. A symbol value is not equal in both passes. 

Register or Register List Expected. 

Right Parenthesis Expected. 

Symbol Expected. 

Undefined Symbol. 
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Debugger 
Error Messages/Conditions 



WHAT? 

The first characters of a command are not recognized. 

SYNTAX ERROR 

Somewhere in the current command, the syntax rules for the command have been violated. 

OVERFLOW 

A number entered or the result of an arithmetic operation cannot be represented in 32 bits. 

BUSERROR 

An address has been accessed which does not exist in the machine's configuration. 

INPUT OVERFLOW 

An internal input stack has overflowed. 

ADDRESS ERROR 

An odd address has been referenced when an even address is required. 

TOO MANY CODES 

Too many escape codes in the ET or ETN list. 

SIZE ERROR 

An entered value does not fit in the required space, e.g., registers. 

TYPE ERROR 

The parameter entered for a command is not the correct type; e.g., an alpha value when a line 
number or address is required. 

EXPRESSION TOO COMPLEX 

The expression requires too much stack space to execute; e.g., more than three levels of 
parentheses. 

DIVIDE BY ZERO 

The value to the right of the / symbol is zero. 

UNDEFINED SYMBOL 

An expression contains a reference to a symbol which the DEBUGGER does not recognize. 

SIZE FIELD TOO BIG 

In a format, the size field is too large for the object being dumped or the format spec being used; 
e.g., the size field for I and U is 1..4. The default size for string data is the length of the string. 

FORMAT REQUIRES MORE DATA 

An attempt has been made to display more bytes than the object contains. 

ADDRESS FORMAT NOT ALLOWED 

The *, < > and " format codes are only allowed if the object is type address. 

PC/SP HAS ODD ADDRESS 

An attempt to return to the user code has been made under the above conditions. 

DUPLICATE BREAK 

GT orTT has specified a location which already has a break point defined. 
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Subject Index 



a 

Absolute symbols 243 

Access command (Filer) 126 

Access rights (SRM) 46,110 

Adding modules to System Library 280 

Addresses (heap) 381 

Addresses (of I/O) 378-9 

Addresses (of RAM) 375-6 

Addresses (of ROM) 377 

Addresses (stack) 381 

Addresses (used by system) 381 

Addressing modes, Assembler 245 

Addressing range 375 

Adjust command (Editor) 74 

ALIAS (Compiler option) 180 

ALLOW_PACKED (Compiler option) .... 181 

ANSI (Compiler option) 182 

Assembler pseudo ops: 

COM 250 

DC 251 

DECIMAL 251 

DEF 252 

DS 252 

END 253 

EQU 253 

INCLUDE 253 

LIST 254 

LLEN 254 

LMODE 255 

LPRINT 255 

MNAME 256 

NOLIST 256 

NOOBJ 257 

NOSYMS 257 

ORG 258 

PAGE 258 

REFA 259 

REFR 259 

RMODE 260 

RORG 260 

SMODE 261 

SPC 261 

SPRINT 261 

SRC 262 

START 262 

TTL 262 



Assembler syntax (diagram) 237 

Assembler: 

Addressing modes 245 

Comment 237,247 

Declaring global variables 229 

Declaring module name 228 

DEF table 226 

Error recovery 233 

Errors 417 

Example modules 263 

Exception coding 235 

Expressions 244 

EXTTable 227 

EXTERNAL procedures 236 

General syntax 237 

IMPORT text 226 

Instruction fields 238 

Introduction 221 

Invoking 222 

Letter case 238 

Line label 238 

Listing 222,224 

Local variables 230 

Module initialization 233 

Modules 225 

Object file 223 

Opcode size suffix 240 

Operand(s) 237,241 

Passing Parameters 228 

Pseudo ops 250 

Source file 222 

Support of co-processor 249 

Syntax 237 

Use of the stack 235 

Assembly language instructions 237 

Available memory (MEMAVAIL) 381 

b 

Backing up volumes 113 

Bad sector command (Filer) 128 

Blocked and unblocked Units 25 

Boot-time errors 408 

Breakpoints (Debugger) 313 



c 

CALLABS (Compiler option) 183 

Change command (Filer) 119,129 

Changing memory contents 322 

Chapter Previews 2,3,4 

Character sets 383 

Co-processor support 249 

Co-processor: 

68881 237 

Co-processors 239 

CODE (Compiler option) 184 

CODE-OFFSETS (Compiler option) 185 

Color highlight characters 394 

Command reference: 

Debugger 333 

Editor 72 

Filer 122 

Librarian 293-5 

Command summary: 

Debugger 73,331,399 

Editor 396 

Filer 397 

Librarian 398 

Main Command Level 395 

Command: 

Krunch (Filer) 140 

Access (Filer) 126 

Adjust (Editor) 74 

Bad sector (Filer) 128 

Change (Filer) 129 

Copy (Editor) 76 

Debugger (summary) 331 

Delete (Editor) 78 

Duplicate (Filer) 131 

Equals ( = ) (Editor) 80 

Exchange (Editor) 100 

eXecute (Main level) 8 

Extended directory (Filer) 132 

Filecopy (Filer) 81 

Find (Editor) 81 

Get (Filer) 139 

Initialize (Main Level) 8,9 

Insert (Editor) 84 

Jump (Editor) 87 

Librarian (Summary) 293-5 

List directory (Filer) 142 

Main Level 5,6 

Make (Filer) 144 

Margin (Editor) 88 

Memory volume (Main Level) 9 

New (Filer) 146 

New sysvol (Main Level) 12 



Page (Editor) 89 

Permanent (Main Level) 13 

Prefix (Filer) 147 

Quit (Editor) 90 

Quit (Filer) 149 

Remove (Filer) 150 

Replace (Editor) 92 

Run (Main Level) 14 

Save (Filer) 152 

Set (Editor) 95 

Stream (Main Level) 15 

Syntax diagram 7 

Translate (Filer) 153 

Unit directory (Filer) 155 

User restart (Main Level) 18 

Verify (Editor) 99 

Version (Main Level) 19 

Volumes (Filer) 157 

What (Filer) 158 

What (Main Level) 21 

Zap (Editor) 102 

Zero (Filer) 159 

Comments, Assembler 237,247 

Compiler option: 

ALIAS 180 

ALLOW.PACKED 181 

ANSI 182 

CALLABS 182 

CODE 184 

CODE_OFFSETS 184 

COPYRIGHT 186 

DEBUG 187 

DEBUG ON 212 

DEF 188 

FLOAT.HDW 189 

General 179 

HEAP_DISPOSE 190 

IF 191 

INCLUDE 192 

IOCHECK 193 

LINENUM 194 

LINES 195 

LIST 196 

OVFLCHECK 197 

PAGE 198 

PAGEWIDTH 199 

PARTIALEVAL 200 

RANGE 201 

REF 202 

SAVE_CONST 203 

SEARCH 204 

SEARCH_SIZE 205 

STACKCHECK 206,212,213 



SWITCH_STRPOS 207 

SYSPROG 208 

TABLES 209 

UCSD 210 

WARN 211 

Compiler: 

Errors 177,413 

Function calls 214 

Function results 215 

Global variables 212 

INCLUDE files 176 

Introduction 161 

Invoking 162 

Listing 163 

Modules 167 

Parameter passing 214 

Procedure calls 213 

Running the program 165 

SEARCH option 173 

Separate module compilation 172 

Stack usage 212 

Static links 217 

Strategy for compiling modules 276 

UCSD options 161 

Workfile 165 

Compiling modules 275 

Constants, Assembler 241 

Copy command (Editor) 76 

Copying: 

Discs 113 

Files 116 

COPYRIGHT (Compiler option) 186 

Creating an SRM Directory 115 

Cursor wheel 54,68 

d 

DEBUG ON (Compiler option) 212,304 

Debugger commands: 

B 335 

BA 335 

BC 336 

BD 336 

BS 337 

CALL 338 

D 339 

DA 341 

DG 341 

EC 342 

ET 342 

ETC 343 



ETN 343 

FB 344 

FH 344 

FI 344 

FO 344 

FU 344 

G 345 

GF 345 

GT 346 

GTF 346 

IF, ELSE, END 347 

OL,OW,OB 349 

PN 350 

PX 350 

Q 351 

QE 351 

QS 351 

Register operations 353 

sb 353 

Softkey commands 352 

T 354 

TD 354 

TQ 354 

TT 355 

WD 356 

WR 356 

WS 356 

Debugger: 

Breakpoint Table 315 

Breakpoints 313 

Changing memory contents 322 

Clearing Breakpoints 316 

Code file specification 306 

Command reference 333 

Command screen 308 

Command summary 331,399 

DEBUG Compiler option 304 

Default display formats 313 

Display formats 310 

Displaying data 310 

Errors 419 

Examining consecutive memory 320 

Examining variables 318 

Example program 304 

Exception trapping 324 

Executing a number of statements 316 

Expressions 333 

Formats for structured variables 321 

Generating Escapes 325 

Input formats 313 

Introduction 303 

Invoking 306 



Is it installed? 306,327 

Key notation 306 

Keyboard 327 

Loading 303,305 

Pause function 316 

Prompt 308 

Queue 310 

Sample session 304 

Screen dumps 310 

Single-stepping 308 

Slow program execution 309 

Stack frame 317 

Static and dynamic links 323 

Tracing program flow 317 

DEF (Compiler option) 188 

DEF table 226,296 

DEF table command (Librarian) 287 

Default display formats (Debugger) 313 

Default volume 22,26,106 

Define Source 296 

Delete command (Editor) 78 

Deleting files 120 

Directory access methods (DAMs) 10,34 

Directory path syntax 30 

Disassembly of a module 265,288-91 

Disc drives 24 

Display formats (Debugger) 311 

Displaying data (with Debugger) 310 

Drive numbers 25 

Duplicate command (Filer) 129 



e 

Editor: 

Anchor 68 

Backing up your file 67 

Changing text 57 

Command summary: Editor 396 

Confirming or aborting commands 53 

Copying text from other files 52 

Creating a text file 49 

Creating text 50,51 

Cursor 68 

Deleting text 55 

Duplicating text 56 

Entering the 48 



Exiting the Editor 66 

File size 69 

Finding text patterns 62 

Formatting text 62 

I/O errors 71 

Introduction 47 

Margining text 64 

Moving text 56 

Moving the cursor 54 

Recovering deleted text 56 

Setting the environment 64,65 

Storing your file 51,66 

Stream Files 71 

Text files 68 

Using workfiles 70 

Window 68 

Equals ( = ) command (Editor) 80 

Error messages 407 

Error recovery 233 

Errors: 

Assembler 417 

Boot-time 408 

Compiler 413 

Debugger 419 

Graphics errors 411 

I/O library 410 

I/O system 409 

Loader/SEGMENTER 412 

Messages 407 

Run-rime 408 

Syntax 163 

Unreported 407 

Examining consecutive memory 

(Debugger) 320 

Examining variables (Debugger) 318 

Exception coding 235 

Exception trapping (Debugger) 324 

eXchange command (Editor) 100 

eXecute Command (Main Level) 8 

EXPORT 298 

Expressions (Debugger) 333 

Expressions, Assembler 244 

EXT table 227,297 

EXT table command (Librarian) 287 

Extended directory command (Filer). . 109,132 

EXTERNAL procedures 236 

External symbols 244 



f 

File directory 272 

File specification 29 

File system: 

Introduction 23 

File types 34 

Filecopy command (Filer) 115,116,135 

Filer: 

Access command 126 

Bad sector command 128 

Change command 119,129 

Command summary 397 

Confirming or aborting commands 104 

Creating a Directory (SRM) 115 

Deleting files 120 

Duplicate command 131 

Entering the Filer 104 

Extended directory command 109,132 

Filecopy command 113,116,135 

Get command 139 

Introduction 103 

Krunch command 140 

Leaving the Filer 121 

List directory command 108,142 

Make command 144 

New command 146 

Prefix command 27, 147 

Prompt 104 

Quit command 149 

Remove command 150 

Removing Files 120 

Save command 152 

SRM access Rights 110 

Translate command 36,111,153 

Unit directory command 155 

Volume back-up 113 

Volumes command 24, 157 

What command 158 

What devices are accessible? 105 

Wildcards Ill 

Workfile 121 

Zero command 159 

Files: 

Creating a text file 49 

Deleting 120 

File specification (syntax) 124 

General Discussion 27 

Interchange between BASIC and Pascal 371 

LIF file names 32 

Names to avoid 39 

Naming Conventions 28 



Object (definition of) 272 

Object modules 165 

Removing 120 

Renaming 119 

Size specification 33 

Specification 29 

SRM concurrent file access 46 

SRM names 33 

Stream 15 

Stream Files 71 

Structure of text files 70 

Suffixes 34 

Suppressing the suffix 35 

Syntax of name 31 

Translating between Data Types 36 

Types 31,34 

Wildcards 37,111 

Workfile 70,121,165 

WS1.0 file names 33 

Find command (Editor) 81 

Rags 298 

FLOAT_HDW (Compiler option) 189 

Formats for structured variables (Debugger) 321 

Function calls 214 

Function results 215 
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General Value or Address Record (GVR) 299 

Generating Escapes (Debugger) 325 

Get command (Filer) 139 

Global base 212 

Global space 20 

Global variables 13,18,212,229,230 

Glossary 401-6 

Glossary (Librarian) 295 

Graphics errors 411 

h 

Heap (addresses) 381 

HEAP_DISPOSE (Compiler option) 190 

Hierarchical directories (SRM) 41 

Highlight characters 394 



1 

I/O addresses 378-9 

I/O library errors 410 

I/O system errors 409 

I/O, memory map 378-9 

IF (Compiler option) 191 

IMPLEMENT 299 

IMPORT 299 

IMPORT text 226 

IMPORT text command (Librarian) 287 

INCLUDE (Compiler option) 192 

INCLUDE files (Compiler) 176 

Initialize Command (Main Level) 9 

Initializing modules 233 

Input formats (Debugger) 313 

Insert command (Editor) 84 

Instruction syntax, Assembler 237 

Interchange of files 371 

Interface text 225,226 

IOCHECK (Compiler option) 193 
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JSR instruction 213 

Jump command (Editor) 87 

k 

Katakana display characters 392-3 

Key notations 1,306 

Keyboard notation (Debugger) 327 

Knob 54,68 

Krunch command (Filer) 140 

1 

Letter case: 
Assembler 238 

LIBRARIAN file 299 

Librarian: 
Adding modules to System Library .... 280 
Command summary 398 



Creating a Boot file 292 

Creating libraries 280 

DEF table 296 

DEF table command 287 

Define Source 296 

Detailed file information 286 

EXPORT 298 

EXT table 297 

EXT table command 287 

Flags 298 

General Value or Address Record (GVR) 299 

Glossary 296 

IMPLEMENT 299 

IMPORT 299 

IMPORT text command 287 

Introduction 271 

Invoking 278 

Libraries 272 

Linking object files together 283 

Making your own library 282 

Mass storage setup 279 

Object file 300 

Object module 300 

REF tables 301 

Reference Pointer 301 

Text Record 302 

Unassemble commands 288-91 

What it does 272 

LIBRARY 277 

Library: 

Definition of 272 

Overview 272 

System 302 

LIF file names 32 

Line label, Assembler 238 

LINENUM (Compiler option) 194 

LINES (Compiler option) 195 

LINK instruction 213,231 

Linking object files 283 

LIST (Compiler option) 196 

List directory command (Filer) 108,142 

Listing files: 

On PRINTER 112 

On screen 112 

Loader/SEGMENTER errors 412 

Local variables 230 

Location counter symbol 242 

Logical units 25 
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Main Command Level 5 

Main Level command summary 395 

Main Level commands 6 

Make command (Filer) 144 

Manual Overview 1,2 

Margin command (Editor) 88 

Mass storage: 

Introduction 23 

Volumes 24 

MC68881 239,249 

MEMAVAIL function 381 

Memory (RAM) 23 

Memory characteristics 23 

Memory map (physical) 375 

Memory map (RAM) 375-6 

Memory map (ROM) 377 

Memory map (software) 381 

Memory volume command (Main Level). . . 10 

Memory-mapped I/O 378-9 

Modules: 

Assembler 225 

Developing and testing 170 

Examples 169,170,174,263-270,272 

How the Compiler finds them 275 

How the loader finds them 277 

Importing 273-7 

Initialization 233 

Names used by operating system 373 

Object (definition of) 272 

Pascal 300 

Separate compilation 172 

Strategy for compiling 170 

Structure of 167 

Monochrome highlight characters 394 

Mouse 54,68 

Moving files 116 
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New command (Filer) 146 

New sysvol Command (Main Level) 12 
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Object file 300 

Object module 300 

Object module (definition of) 272 

On-Line devices 9 

Opcode: 

Assembler 237,239 

Co-processor 239 

Processor 239 

Size suffixes 240 

Operand components, Assembler 246 

Operand(s): 

Components 241 

Constants 241 

Description 237,241 

Location counter symbol 242 

Symbol type 243 

Symbols 242 

Other manuals 1,2 

OVFLCHECK (Compiler option) 197 
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PAGE (Compiler option) 198 

Page command (Editor) 89 

PAGEWIDTH (Compiler option) 199 

Parameter passing 214 

PARTIAL_EVAL (Compiler option) 200 

Pascal 1.0 (description) 357 

Pascal 2.0 (description) 359 

Pascal 3.0 (description) 362 

Pascal 3.01 (description) 366 

Pascal 3. 1 (description) 367 

Pascal stack 212 

Pascal system history 357 

Pascal: 

Description of extensions 161 

Module 300 

Source program 186 

Volumes 24 

Passing parameters 228 

Passwords (SRM files) 46 

Permanent Command (Main Level) 13 

Physical memory map 375 

Prefix command (Filer) 27, 147 

Prefix volume 26 



Problems: 

Compiler 177 

File names to avoid 39 

Insufficient global space 178 

No room on volume 40 

Not Enough Memory 178 

Syntax errors 163 

Procedure calls (effects on stack) 213 

Procedures, EXTERNAL 236 

Processor, 68020 237 

Programming system 225 

Prompts: 

Date 20 

Debugger 308 

Editor 49 

Filer 104 

Main Level 5 

Time 20 
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Queue (Debugger) 310 

Quit command (Editor) 90 

Quit command (Filer) 149 
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RAM memory 23 

RAM memory map 375-6 

RANGE (Compiler option) 201 

Range of addresses 375 

REF (Compiler option) 202 

REF tables 301 

Reference Pointer 301 

Register symbols 242 

Relative symbols 244 

Remove command (Filer) 150 

Removing Files 120 

Renaming files 119 

Renaming volumes 119 

Replace command (Editor) 92 

ROM addresses 377 

ROM memory map 377 

Run Command (Main Level) 14 

Run-time errors 408 
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Save command (Filer) 152 

SAVE_CONST (Compiler option) 203 

Screen dumps (Debugger) 310 

SEARCH (Compiler option) 204 

SEARCFLSIZE (Compiler option) 205 

Set command (Editor) 95 

Single stepping a program 309 

Size suffixes of opcodes 240 

Slow program execution 309 

Software memory map 381 

Source program 162 

SRM: 

Access rights 46,110 

Concurrent file access 46 

Creating a Directory 115 

Current working volume 43 

Default volume 45 

Directories 41 

Directory structure 41 

File names 33 

File notation 42 

Passwords 46 

Unit numbers 42 

Volumes 42 

Stack (addresses) 381 

Stack (How Pascal uses it) 212 

Stack frame (Debugger) 318 

STACKCHECK (Compiler option) . . . 206,212 
STACKCHECK ON (Compiler option) ... 213 

Static and dynamic links (Debugger) 323 

Static links (Compiler) 217 

Stream Command (Main Level) 15 

Stream files 71 

Subsystems 5 

Suffix Suppression 35 

Suffixes 34 

Summary: 

Debugger commands 331 

Editor commands 72 

Filer Commands 122 

Librarian commands 293-5 

SWITCH_STRPOS (Compiler option). ... 207 
Symbol types: 

Absolute 243 

External 244 

Register 243 

Relative 244 

User-defined 243 



Symbols 242 

Syntax diagram (explanation) 7 

SYSPROG (Compiler option) 208 

System addresses 381 

System File Table 12,21 

System files 12,21 

System history 357 

System Library 8,12,22,277,302 

System version 19 

System volume: 

General 12,22,107 

Purpose of 26 
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TABLE program: 

General. 9 

TABLES (Compiler option) 209 

Text files: 

Creating 50,51 

Structure of 70 

Text Record 302 

Translate command (Filer) 36,111,153 

TRAP instruction 213,231 
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U.S. ASCII characters 384-5 

U.S. /European display characters 386-91 

UCSD (Compiler option) 210 

Unassemble commands (Librarian) . . . 288-91 

Unit directory command (Filer) 155 

Unit numbers: 

Defined 25 

General 9,10,12 

Unit Table 9,10,25 

Units (blocked vs unblocked) 25 

UNLK instruction 214 

Unreported errors 407 

User restart Command (Main Level) 18 

User-defined symbols 243 

Using the stack 235 
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Variables, global 18,20 

Variables, zeroing 18 

Variables: 

Global 13 

Zeroing 13 

Verify command (Editor) 99 

Version Command (Main Level) 19 

Volume ID 29 

Volumes command (Filer) 24,105,157 

Volumes: 

Backing up 113 

Default Volume 26 

Defined 24 

General 24 

Pascal 24 

Prefix Volume 26 

Renaming 119 

Specification (syntax) 125 

Syntax of identifier 29 

System Volume 26 
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WARN (Compiler option) 211 

What command (Filer) 158 

What Command (Main Level) 21 

Wildcards 37,111 

Workfile 121,165 

Workfiles 70 

WS1.0 file names 33 



Zap command (Editor) 102 

Zero command (Filer) 159 
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